free-search-mcp

👁 License
👁 Python
👁 MCP

Сервер протокола Model Context Protocol, работающий преимущественно локально и не требующий API-ключей. Он дает любой LLM (Claude, GPT, локальная Ollama и т. д.) возможность искать в интернете, загружать и очищать страницы, а также читать документы — без необходимости регистрироваться в каком-либо поисковом API.

Он объединяет лучшие идеи из нескольких MCP с открытым исходным кодом в один пакет Python и добавляет эргономику для LLM и надежность, которых им не хватало.

research("how does reciprocal rank fusion work", depth=3)
 ↓
# Research brief: how does reciprocal rank fusion work
_engines: duckduckgo, mojeek, startpage · sources: 3 · ~3,400 tokens_

## Sources
- [1] Reciprocal rank fusion | Elasticsearch Reference — <https://…>
- [2] Hybrid Search Scoring (RRF) | Microsoft Learn — <https://…>
- [3] RRF explained in 4 mins — Medium — <https://…>

## Documents
…full Markdown bodies of each page, ready for the LLM to read…

Один вызов инструмента. Три источника. Никаких API-ключей. Никаких требований OPENAI_API_KEY для поиска.

Зачем это нужно

Существующие MCP для поиска хорошо справляются с чем-то одним, но обычно вам нужно всё сразу:

«Настройка под LLM» здесь означает: вывод в формате Markdown, оценка количества токенов, умное усечение на границах абзацев, строки документации «Best for / Not for / Returns / Common mistakes», которые модель использует для выбора правильного инструмента, полезные подсказки об ошибках, шаблоны промптов и ресурсов MCP, а также однократный вызов research(), который объединяет поиск→загрузку→загрузку→загрузку в один шаг.

«Trafilatura» означает, что мы извлекаем основной контент с помощью trafilatura — победителя теста ROUGE 2023 года (около 0,85 против 0,55 для простого удаления шаблонного кода). Каждая загруженная страница также бесплатно возвращает author, published_date и sitename.

«Фильтры» означают, что поиск/исследование принимают параметры freshness, include_domains, exclude_domains, category (news/pdf/github/paper/forum/blog), include_text, exclude_text.

Related MCP server: TOOL4LM

Инструменты

Плюс 2 промпта MCP (Research thoroughly, Fact-check claim) и шаблон ресурса (cache://page/{url}) для возврата кэшированных страниц в контекст без повторной загрузки.

Фильтры (search / research)

Все инструменты по умолчанию используют format="markdown" — читабельно, примерно на 40% меньше токенов, чем JSON, с указанием источника и заголовком бюджета токенов. Передайте format="json" для структурированного доступа.

Аннотации инструментов

Каждый инструмент поставляется с правильными аннотациями readOnlyHint, idempotentHint и openWorldHint, чтобы клиенты MCP могли помечать их и ограничивать выполнение действий с повышенными привилегиями.

Движки

Набор по умолчанию (все надежные, без капчи при повторных вызовах): duckduckgo, mojeek, startpage.

Опционально (периодические проверки для headless-клиентов): brave, bing, baidu.

Brave/Bing/Baidu блокируют headless-браузеры после нескольких вызовов (PoW CAPTCHA, страницы «что-то пошло не так», редиректы). Передавайте engines=["brave"] и т. д. только тогда, когда стандартные движки не могут найти то, что вам нужно.

Установка

git clone https://github.com/ymylive/free-search-mcp.git
cd free-search-mcp
uv sync
uv run playwright install chromium

Запуск в качестве автономного сервера (транспорт stdio):

uv run search-mcp

Запуск живых тестов (обращаются к реальному интернету — установите переменную окружения):

SEARCH_MCP_TEST_NETWORK=1 uv run pytest -v

Офлайн-тесты запускаются по умолчанию и не используют сеть.

Подключение к Claude Desktop

Добавьте это в ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) или эквивалентный файл на вашей платформе:

{
 "mcpServers": {
 "search": {
 "command": "uv",
 "args": ["--directory", "/absolute/path/to/free-search-mcp", "run", "search-mcp"]
 }
 }
}

Перезапустите Claude Desktop. Семь инструментов выше появятся в панели инструментов.

Подключение к другим клиентам

Сервер использует обычный MCP через stdio. Работает всё, что поддерживает MCP:

• Claude Code (claude mcp add search uv --directory /…/free-search-mcp run search-mcp)

• Cursor / Continue / Cline (используйте фрагмент JSON выше)

• Пользовательские клиенты на Python / TypeScript через официальный SDK MCP

Конфигурация

Все настройки можно переопределить с помощью переменных окружения с префиксом SEARCH_MCP_:

Архитектура

 ┌─────────────────────────────────────────────────────┐
 │ FastMCP server (stdio) │
 │ tools: search / research / fetch / fetch_batch / │
 │ read_doc / cache_search / engines │
 └────────────┬────────────────────────────────────────┘
 │
 ┌────────────▼────────────┐ ┌────────────────────────┐
 │ aggregator │ │ fetcher │
 │ - parallel engines │ │ - httpx fast path │
 │ - reciprocal rank │ │ - playwright fallback │
 │ fusion │ │ - markdownify │
 │ - search cache (FTS5) │ │ - page cache (FTS5) │
 └────┬────────────────────┘ └────────────┬───────────┘
 │ │
 ┌────▼─────────────────┐ ┌──────────────▼─────────────┐
 │ engines/ │ │ browser pool │
 │ duckduckgo.py │ │ - persistent context │
 │ mojeek.py │ │ - stealth init script │
 │ startpage.py │ │ - shared cookies │
 │ brave.py (opt) │ │ - semaphore-bounded pages│
 │ bing.py (opt) │ └────────────────────────────┘
 │ baidu.py (opt) │
 └──────────────────────┘

 ┌────────────────────────────┐ ┌──────────────────┐
 │ documents/ │ │ ratelimit │
 │ pypdf, python-docx, │ │ token bucket │
 │ markdownify │ │ per engine │
 └────────────────────────────┘ └──────────────────┘

 ┌────────────────────────────┐ ┌──────────────────┐
 │ formatting │ │ research │
 │ token estimate │ │ composed │
 │ smart truncation │ │ workflow │
 │ markdown renderers │ │ │
 └────────────────────────────┘ └──────────────────┘

Паттерн адаптера движка

Каждый движок в src/search_mcp/engines/ реализует:

class Engine:
 name: str
 needs_browser: bool # Force Playwright?
 wait_selector: str | None # CSS to wait for in browser mode

 def build_url(self, query: str, max_results: int) -> str: ...
 def parse(self, html: str) -> list[SearchResult]: ...

Базовый класс обрабатывает транспорт (httpx → откат к Playwright), ограничение частоты запросов и случай, когда HTTP возвращает капчу вместо результатов (автоматические повторные попытки через браузер).

Благодарности

Этот проект стоит на плечах гигантов:

• mrkrsl/web-search-mcp — умная стратегия загрузки httpx-затем-Playwright, цепочка отката по нескольким движкам

• Aas-ee/open-webSearch — широта охвата движков (Bing/DDG/Baidu/Brave/Startpage)

• VincentKaufmann/noapi-google-search-mcp — паттерны защиты от обнаружения (navigator.webdriver, UA, cookies), идея кэша SQLite FTS5, многоформатный read_document

• nickclyde/duckduckgo-mcp-server — ограничение частоты запросов на движок, очистка контента для LLM

• Mojeek — независимый поисковый индекс, который не блокирует по User-Agent

• Model Context Protocol и официальный Python SDK

Лицензия

MIT — см. LICENSE.

Maintenance

Resources

• GitHub Repository
Need Help?Related Servers

Tools

• cache_searchA
• compareA
• enginesA
• extract_structuredA
• fetchA
• fetch_batchA
• read_docA
• researchA