free-search-mcp

👁 License
👁 Python
👁 MCP

Ein Local-First-MCP-Server ohne API-Key (Model Context Protocol), der jedem LLM (Claude, GPT, lokales Ollama, …) die Fähigkeit verleiht, das Web zu durchsuchen, Seiten abzurufen und zu bereinigen sowie Dokumente zu lesen – ohne dass Sie sich für eine einzige Such-API registrieren müssen.

Er bündelt die besten Ideen einer Handvoll Open-Source-MCPs in einem Python-Paket und ergänzt die LLM-Ergonomie und Zuverlässigkeit, die bei den jeweiligen Projekten fehlten.

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…

Ein Tool-Aufruf. Drei Quellen. Kein API-Key. Keine OPENAI_API_KEY-für-Suche-Abzocke.

Warum gibt es dieses Projekt?

Bestehende Such-MCPs erledigen jeweils eine Sache gut, aber meistens möchte man alles davon:

"LLM-optimiert" bedeutet hier: Markdown-fokussierte Ausgabe, Token-Schätzungen, intelligentes Kürzen an Absatzgrenzen, Docstrings für "Best for / Not for / Returns / Common mistakes", die das Modell nutzt, um das richtige Tool auszuwählen, hilfreiche Fehlermeldungen, MCP-Prompts und Ressourcenvorlagen sowie ein One-Shot-research(), das Suche→Abruf→Abruf→Abruf in einem einzigen Durchgang zusammenfasst.

"Trafilatura" bedeutet, dass wir Hauptinhalte mit trafilatura extrahieren – dem Gewinner des Bevendorff 2023 ROUGE-Benchmarks (~0,85 gegenüber ~0,55 bei naivem Entfernen von Boilerplate). Jede abgerufene Seite liefert zudem kostenlos author, published_date und sitename.

"Filter" bedeutet, dass Suche/Recherche freshness, include_domains, exclude_domains, category (news/pdf/github/paper/forum/blog), include_text und exclude_text akzeptieren.

Related MCP server: TOOL4LM

Tools

Zusätzlich 2 MCP-Prompts (Research thoroughly, Fact-check claim) und eine Ressourcenvorlage (cache://page/{url}), um zwischengespeicherte Seiten ohne erneuten Abruf wieder in den Kontext zu ziehen.

Filter (Suche / Recherche)

Alle Tools verwenden standardmäßig format="markdown" – lesbar, ca. 40 % weniger Token als JSON, mit Herkunftsnachweis und einem Token-Budget-Header. Verwenden Sie format="json" für strukturierten Zugriff.

Tool-Annotationen

Jedes Tool enthält korrekte readOnlyHint-, idempotentHint- und openWorldHint-Annotationen, damit MCP-Clients diese kennzeichnen und erweiterte Aktionen einschränken können.

Engines

Standard-Set (alle zuverlässig, keine Captchas bei wiederholten Aufrufen): duckduckgo, mojeek, startpage.

Optional (gelegentliche Herausforderungen für Headless-Clients): brave, bing, baidu.

Brave/Bing/Baidu blockieren Headless-Browser nach einigen Aufrufen (PoW-CAPTCHAs, "Etwas ist schiefgelaufen"-Seiten, Redirect-Wrapper). Verwenden Sie engines=["brave"] usw. nur, wenn die Standardeinstellungen nicht finden, was Sie benötigen.

Installation

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

Ausführung als eigenständiger Server (stdio-Transport):

uv run search-mcp

Live-Tests ausführen (greift auf das echte Web zu – Umgebungsvariable setzen):

SEARCH_MCP_TEST_NETWORK=1 uv run pytest -v

Offline-Tests laufen standardmäßig und greifen nicht auf das Netzwerk zu.

Einbindung in Claude Desktop

Fügen Sie dies zu ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) oder dem entsprechenden Pfad auf Ihrer Plattform hinzu:

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

Starten Sie Claude Desktop neu. Die sieben oben genannten Tools erscheinen in der Tool-Leiste.

Einbindung in andere Clients

Der Server spricht einfaches MCP über stdio. Alles, was MCP unterstützt, funktioniert:

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

• Cursor / Continue / Cline (verwenden Sie den JSON-Schnipsel oben)

• Eigene Python / TypeScript-Clients über das offizielle MCP-SDK

Konfiguration

Alle Einstellungen können durch Umgebungsvariablen mit dem Präfix SEARCH_MCP_ überschrieben werden:

Architektur

 ┌─────────────────────────────────────────────────────┐
 │ 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 │ │ │
 └────────────────────────────┘ └──────────────────┘

Engine-Adapter-Muster

Jede Engine in src/search_mcp/engines/ implementiert:

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]: ...

Die Basisklasse übernimmt den Transport (httpx → Playwright-Fallback), das Rate-Limiting und den Fall, dass HTTP statt Ergebnissen eine Captcha-Seite zurückgibt (automatische Wiederholung über den Browser).

Credits

Dieses Projekt basiert auf der Arbeit von:

• mrkrsl/web-search-mcp — intelligente httpx-dann-Playwright-Abrufstrategie, Multi-Engine-Fallback-Kette

• Aas-ee/open-webSearch — Multi-Engine-Breite (Bing/DDG/Baidu/Brave/Startpage)

• VincentKaufmann/noapi-google-search-mcp — Anti-Erkennungs-Muster (navigator.webdriver, UA, Cookies), SQLite-FTS5-Cache-Idee, Multi-Format read_document

• nickclyde/duckduckgo-mcp-server — Rate-Limiting pro Engine, LLM-freundliche Inhaltsbereinigung

• Mojeek — unabhängiger Suchindex, der nicht nach User-Agent blockiert

• Model Context Protocol und das offizielle Python-SDK

Lizenz

MIT — siehe LICENSE.

Maintenance

Resources

• GitHub Repository
Need Help?Related Servers

Tools

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