Web Research MCP

Ein hochwertiger, quellenübergreifender Web-Recherche-MCP-Server für KI-Agenten. Schließen Sie ihn an Claude Desktop, Hermes, Cursor oder einen beliebigen MCP-kompatiblen Client an und erhalten Sie produktionsreife Suche + Seitenabruf über Wikipedia, arXiv, Hacker News, Stack Exchange, Crossref, Brave, Tavily und jede beliebige URL im Web.

# One-line install (anywhere on disk)
git clone https://github.com/infinit3labs/web-research-mcp.git
hermes mcp add web-research --command "$(pwd)/web-research-mcp/bin/web-research-mcp"
# 6 of 7 tools work with zero API keys. Add Brave or Tavily to unlock general web search.

Warum es das gibt

Die meisten „Websuch“-MCP-Server versuchen, Google über einen Headless-Browser mit zufälligen Fingerprints zu scrapen. Dieser Ansatz ist ein aussichtsloses Wettrüsten – Suchmaschinen erkennen und sperren Scraper innerhalb von Tagen, und selbst wenn es funktioniert, erhalten Sie DOM-Suppe, die Ihr LLM erst bereinigen muss.

Dieser Server verfolgt einen anderen Ansatz – er spricht mit APIs, die für Agenten gebaut wurden:

Alle sieben Quellen funktionieren ohne API-Schlüssel. Mit einem Brave- oder Tavily-Schlüssel schalten Sie die Echtzeit-Websuche frei. Das ist der qualitativ hochwertigste Ansatz – Sie erhalten bessere Ergebnisse als beim Scraping, weil echte Web-Index-APIs Signale (Klickmodelle, Aktualität, Linkanalyse) nutzen, die kein Scraper nachbilden kann.

Schnellstart

Option A – pip install (sobald veröffentlicht)

pip install deep-web-research-mcp
hermes mcp add web-research --command "$(which web-research-mcp)"

Hinweis zur Benennung. Der PyPI-Verteilungspaketname lautet deep-web-research-mcp (also pip install deep-web-research-mcp), aber die ausführbare Datei in Ihrem PATH heißt nach der Installation web-research-mcp (definiert durch [project.scripts] in pyproject.toml). Das ist beabsichtigt – die ausführbare Datei entspricht dem lokalen Launcher bin/web-research-mcp und dem MCP-Registrierungsnamen web-research. Gleiches Paket, zwei Namen.

Option B – Aus dem Quellcode klonen

git clone https://github.com/infinit3labs/web-research-mcp.git
hermes mcp add web-research \
  --command "$(pwd)/bin/web-research-mcp"

Akzeptieren Sie bei der Eingabeaufforderung alle 7 Tools. Fertig.

Option C – Mit Claude Desktop installieren

Bearbeiten Sie ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "web-research": {
      "command": "/Users/code/mcp-servers/web-research/bin/web-research-mcp"
    }
  }
}

Option D – Mit Cursor / einem beliebigen stdio-MCP-Client installieren

{
  "mcpServers": {
    "web-research": {
      "command": "/absolute/path/to/web-research-mcp/bin/web-research-mcp"
    }
  }
}

Das Launcher-Skript erstellt beim ersten Start automatisch eine virtuelle Umgebung, installiert Abhängigkeiten aus pyproject.toml und lädt web-research.env für alle konfigurierten API-Schlüssel.

2. (Optional) API-Schlüssel für die echte Websuche hinzufügen

cp web-research.env.example web-research.env
$EDITOR web-research.env

Der Launcher liest die Schlüssel bei jedem Aufruf aus web-research.env – kein Neustart Ihres MCP-Clients erforderlich.

3. Verwenden

Fragen Sie Ihren Agenten zum Beispiel:

„Durchsuche Hacker News und Stack Overflow nach den besten MCP-Servern, die 2026 veröffentlicht wurden"

„Verwende pro_mode, um den aktuellen Stand kleiner Sprachmodelle zu recherchieren"

„Rufe https://arxiv.org/abs/2506.06962 ab und fasse die Methodik zusammen"

„Gleiche diese Behauptung mit Wikipedia und arXiv ab"

Tools

Alle 10 Tools sind in tools/list registriert. Die Tools sind in zwei Ebenen unterteilt:

• Suche & Abruf (7 Tools) – einmalige Abfragen. Ein Tool, eine API, ein Ergebnis.

• Tiefenrecherche (3 Tools) – mehrstufige Pipelines, die Belege planen, sammeln und strukturieren. Verwenden Sie diese, wenn eine einzelne Suche nicht ausreicht.

Suche & Abruf

search_web – Mehrquellen-Websuche

search_web(
    query: str,                  # search query
    max_results: int = 10,       # per source, before dedup (1–30)
    pro_mode: bool = False,      # also fetch top 3 URLs and append excerpts
) -> str

Unterstützt durch Brave + Tavily mit URL-Kanonisierung, Deduplizierung und quellenübergreifender Bewertungsverstärkung. Erfordert BRAVE_API_KEY und/oder TAVILY_API_KEY. Ohne Schlüssel wird eine klare Meldung angezeigt, die erklärt, wie Sie die Funktion aktivieren.

pro_mode: true ist das Killer-Feature für die Recherche – es führt eine normale Suche durch, ruft die Top-3-Ergebnisse über Jina ab und hängt den Inhalt als Snippet an. Ein einziger Aufruf ersetzt search_web + 3 × fetch_url.

fetch_url – Sauberes Markdown einer beliebigen Seite

fetch_url(url: str) -> str

Läuft über Jina Reader, das:

• JS-lastige Seiten rendert (SPAs, React-Apps)

• die meisten Bot-Erkennungen umgeht (Jina ist auf der Whitelist)

• sauberes Markdown mit Metadatenblock zurückgibt (Title:, URL Source:, Published Time:)

• auf ~20.000 Zeichen kürzt, um Ihren Kontext zu schützen

search_wikipedia – Enzyklopädische Verankerung

search_wikipedia(query: str, max_results: int = 5) -> str

Wikipedia MediaWiki API. Ohne Schlüssel. Schnell. Am besten für Definitionen und historischen Kontext.

search_academic – arXiv-Preprints

search_academic(query: str, max_results: int = 5) -> str

Gibt Titel, Autoren, Abstract-Auszug, Veröffentlichungsdatum und PDF-URL zurück. Ohne Schlüssel. Am besten für Informatik, Physik, Mathematik und Biologie.

search_news – Hacker-News-Signal

search_news(query: str, max_results: int = 10) -> str

Gibt Titel, URL, Punkte, Kommentare und Datum zurück. Ohne Schlüssel. Am besten für aktuelle Tech-Trends.

search_stackexchange – Fragen & Antworten aus über 180 Sites

search_stackexchange(query: str, max_results: int = 5, site: str = "stackoverflow") -> str

Setzen Sie site auf eine beliebige SE-Community: serverfault, superuser, askubuntu, math, tex, datascience, ai usw. Ohne Schlüssel.

search_scholar_meta – Peer-reviewte Paper über Crossref

search_scholar_meta(query: str, max_results: int = 5) -> str

Gibt Titel, DOI, Zitationsanzahl, Verlag, Veröffentlichungsdatum und Abstract zurück. Deckt Paper ab, die arXiv nicht hat (Elsevier, Springer, Wiley, IEEE, ACM). Ohne Schlüssel.

Tiefenrecherche

Diese drei Tools setzen die oben genannten Such-/Abruf-Primitive zu mehrstufigen Recherche-Workflows zusammen. Sie rufen selbst nie ein LLM auf – das aufrufende Modell bleibt für die endgültige Ausarbeitung verantwortlich; der Server plant, sammelt und strukturiert Belege mit überprüfbaren Zitaten.

plan_research – Nur strukturierter Plan (keine Abrufe)

plan_research(question: str, depth: str = "standard") -> str  # JSON

Gibt einen JSON-Forschungsplan zurück: Unterfragen, empfohlene Quellen pro Unterfrage, Begründung, auszuführende Abfragen sowie geschätzte Suchen und Abrufe. Verwenden Sie dies, wenn Sie den Plan vor der Ausführung der vollständigen Pipeline einsehen oder ändern möchten.

• depth: "quick" (2–3 Unterfragen), "standard" (4–6), "deep" (6–8)

extract_evidence – Gezielte Zitate aus einer URL

extract_evidence(
    url: str,
    question: str,
    max_passages: int = 5,
) -> str  # JSON

Ruft die URL über Jina ab, teilt sie in Absätze auf, bewertet jeden nach Relevanz für Ihre Frage und gibt die besten Passagen zurück. Jede Passage enthält before-/quote-/after-Kontext, einen relevance-Wert (0–1) und einen offset (Zeichenposition in der Quelle), sodass Zitate unabhängig überprüfbar sind.

Verwenden Sie dies, wenn Sie bereits eine bestimmte Quelle haben und daraus Belege für eine enge Behauptung gewinnen möchten.

research – Vollständige Tiefenrecherche-Pipeline

research(question: str, depth: str = "standard") -> str  # markdown + JSON

Ende-zu-Ende-Recherche-Workflow:

1. Planen – erstellt den Unterfragen-Plan

2. Verteilen – durchsucht die empfohlenen Quellen für jede Unterfrage parallel

3. Bewerten – dedupliziert URLs über den gesamten Plan und bewertet sie mit quellenbewusster zusammengesetzter Gewichtung (Wikipedia/arXiv/Crossref 2,0×, Stack Exchange 1,7×, Websuche 1,5×, Hacker News 1,0×)

4. Abrufen – ruft die Top-URLs über Jina Reader ab

5. Extrahieren – bewertet Absätze nach Relevanz mit einer Qualitätsuntergrenze (filtert Navigationsmenüs, reine Link-Absätze und Fußzeilen-Müll heraus)

6. Zurückgeben – erzeugt einen strukturierten ResearchReport:

{
  "question": "What is retrieval augmented generation?",
  "depth": "quick",
  "plan": { "sub_questions": [...], "estimated_searches": 4, ... },
  "citations": [
    { "id": 1, "url": "...", "title": "...", "source": "wikipedia", "quotes": 2 }
  ],
  "evidence": {
    "sq_def": [
      { "citation_id": 1, "relevance": 0.78, "offset": 1234,
        "before": "...", "quote": "...", "after": "..." }
    ]
  },
  "synthesis_template": "# Research Report: ..."
}

Die synthesis_template ist ein Markdown-Gerüst mit einem Abschnitt pro Unterfrage plus einer Quellentabelle. Sie (das Modell) füllen die Erzählung aus und verweisen mit jedem [n]-Marker auf den entsprechenden Eintrag in citations. Jede zitierte Passage trägt einen Zeichen-offset, damit ein Leser das Zitat anhand der Originalseite überprüfen kann.

depth steuert die Breite:

• "quick" – 2–3 Unterfragen, ~6 Abrufe, ~2 Minuten

• "standard" – 4–6 Unterfragen, ~20 Abrufe, ~3 Minuten

• "deep" – 6–8 Unterfragen, ~32 Abrufe, ~5 Minuten

Architektur

┌─────────────────────────────────────────────────────────┐
│                    MCP Client                            │
│  (Claude Desktop, Hermes, Cursor, custom agent)          │
└────────────────────┬────────────────────────────────────┘
                     │ JSON-RPC over stdio
                     ▼
┌─────────────────────────────────────────────────────────┐
│              bin/web-research-mcp                         │
│  • Boots venv (or reuses cached one)                     │
│  • Sources web-research.env for API keys                 │
│  • Execs python -m web_research.server                   │
└────────────────────┬────────────────────────────────────┘
                     ▼
┌─────────────────────────────────────────────────────────┐
│           web_research.server (MCPServer)                 │
│  7 tool functions registered via @app.tool() decorator    │
│  • Pydantic-driven JSON schemas from type hints           │
│  • Single shared httpx.AsyncClient per call              │
│  • Graceful degradation: one bad source ≠ failed call    │
└────────────────────┬────────────────────────────────────┘
                     │ asyncio.gather for parallel fan-out
                     ▼
┌─────────────────────────────────────────────────────────┐
│          web_research.providers (7 backends)              │
│  ┌──────────┐ ┌──────────┐ ┌─────────────┐               │
│  │ brave    │ │ tavily   │ │ jina_fetch  │  ← general web│
│  └──────────┘ └──────────┘ └─────────────┘               │
│  ┌──────────┐ ┌──────────┐ ┌─────────────┐               │
│  │ wikipedia│ │ arxiv    │ │ crossref    │  ← academic   │
│  └──────────┘ └──────────┘ └─────────────┘               │
│  ┌──────────┐ ┌──────────┐                                │
│  │ hn_algolia│ │stackex   │  ← tech signal               │
│  └──────────┘ └──────────┘                                │
│  + merge_results() with URL-canonical dedup               │
└─────────────────────────────────────────────────────────┘

Wichtige Designentscheidungen

API-first statt Scrape-first. Das ist die Kernthese. Jede Quelle ist eine offizielle API, die für den programmatischen Zugriff entwickelt wurde. Sie erhalten saubere, strukturierte Daten, keine IP-Sperren und keinen Wartungsaufwand bei Website-Redesigns.

Fehlerisolierung pro Quelle. Jeder Anbieter kapselt seinen HTTP-Aufruf in try/except. Ein 429 einer Quelle bringt nie die gesamte Suche zu Fall – Sie erhalten Teilergebnisse plus eine klare Meldung, welche Quelle fehlgeschlagen ist.

URL-Kanonisierung. merge_results() entfernt Tracking-Parameter (utm_*, fbclid, gclid, ref) vor der Deduplizierung, normalisiert die Groß-/Kleinschreibung des Hosts und entfernt Fragmente. Wenn Brave und Tavily denselben Artikel zurückgeben, sehen Sie ihn einmal mit also_found_in: [brave, tavily] und einem erhöhten Score.

Gemeinsamer HTTP-Client pro Aufruf. httpx.AsyncClient mit Verbindungspooling (max_connections=20), sinnvollen Timeouts (Standard 30s, 45s für fetch_url) und automatischer Weiterleitungsverfolgung. Neuer Client pro Aufruf, da stdio-MCP-Server jeweils eine Anfrage verarbeiten und wir einen sauberen Zustand wünschen.

Keine Headless-Browser. Kein Playwright, Selenium, Puppeteer oder Proxy-Rotation. Kleinere Angriffsfläche, weniger Abhängigkeiten, kein JVM-/Chrome-Fußabdruck. Jina übernimmt die schwere Arbeit bei den wenigen Seiten, die JS-Rendering benötigen.

Vergleich mit Alternativen

Testen

.venv/bin/python tests/e2e_protocol.py

Dies startet den eigentlichen Server, führt einen echten MCP-initialize- + tools/list-Handshake durch und tätigt dann Live-JSON-RPC-Aufrufe an jedes Tool. Dabei wird überprüft, dass:

• Echte APIs echte Daten zurückgeben (keine Stubs)

• Die Antwort jedes Tools die erwartete Form hat

• Fehlerzustände ordnungsgemäß behandelt werden

• search_web ohne Schlüssel eine klare „API-Schlüssel festlegen“-Meldung zurückgibt

Letzter Lauf: 7/7 Tools bestehen gegen Live-APIs.

Fehlerbehebung

Server startet, aber Tools werden in meinem MCP-Client nicht angezeigt

Prüfen Sie hermes mcp list (oder das Äquivalent). Der Server ist mit --command registriert, was bedeutet, dass Hermes den Launcher direkt ausführt. Stellen Sie sicher, dass der Launcher ausführbar ist:

chmod +x bin/web-research-mcp

fetch_url gibt abgeschnittenen Inhalt zurück

Bewusst konzipiert — das 20k-Zeichenlimit schützt dein Kontextfenster. Bei längeren Inhalten ruf die Seite selbst ab und übergib search_web Auszüge für Folgefragen, oder teile den Inhalt über mehrere Aufrufe in Abschnitte auf.

search_web gibt „No web results. This is likely because no API key is configured“ zurück

Mindestens eine der Umgebungsvariablen BRAVE_API_KEY oder TAVILY_API_KEY muss in web-research.env gesetzt sein. Die 6 anderen Tools (Wikipedia, arXiv, HN, Stack Exchange, Crossref, fetch_url) funktionieren alle ohne Schlüssel.

Stack Exchange gibt 400 Bad Request zurück

Wenn du einen benutzerdefinierten filter-Parameter konfiguriert hast, lehnt die API unbekannte Filter-IDs ab. Verwende den Standardfilter (lass den Parameter weg) — er liefert dir mehr Felder zurück, als du brauchst, aber alles funktioniert. Dieser Server verwendet den Standardfilter.

Server stürzt beim ersten Start ab

Prüfe stderr auf den eigentlichen Traceback. Häufige Ursache: Python <3.10. Überprüfe das mit python3 --version.

Zugriffsbegrenzungen

Jede API ohne Schlüssel hat ihre eigenen Grenzen. Wenn du sie erreichst:

• Wikipedia: ~200 req/min, identifiziere dich mit einem echten User-Agent (diesen sendet dieser Server)

• arXiv: ~1 req/3s für nicht authentifizierte Anfragen, bitte halte dich zurück

• Hacker News Algolia nach Analyse der Antwort: 10k req/Stunde mit API-Schlüssel, 5k ohne

• Stack Exchange: 300 req/Tag ohne Schlüssel (für Suchsitzungen ausreichend)

• Crossref: bitte eine mailto-Adresse im User-Agent angeben (macht dieser Server), dann ist es im polite-pool unbegrenzt

Entwicklung

Projektlayout

web-research-mcp/
├── bin/
│   └── web-research-mcp          # Launcher: venv bootstrap + exec
├── src/web_research/
│   ├── __init__.py
│   ├── server.py                  # MCPServer + 7 @app.tool functions
│   └── providers.py               # 7 search backends + Result dataclass
├── tests/
│   └── e2e_protocol.py            # Real subprocess JSON-RPC test
├── web-research.env.example       # API key template
├── pyproject.toml                 # PEP 621, uv-installable
├── README.md
├── CHANGELOG.md
├── LICENSE
└── .gitignore

Neues Tool hinzufügen

1. Füge eine asynchrone Funktion in providers.py hinzu:

   async def search_my_source(query: str, max_results: int, client: httpx.AsyncClient) -> list[Result]:
       try:
           # ... your HTTP call ...
       except Exception as e:
           print(f"[my_source] error: {e}", flush=True)
           return []
       return [Result(title=..., url=..., snippet=..., source="my_source")]

2. Registriere sie in server.py:

   @app.tool(name="search_my_source", description="...", annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True))
   async def search_my_source(query: Annotated[str, Field(description="Search query")], max_results: Annotated[int, Field(ge=1, le=10, default=5)] = 5) -> str:
       async with await _new_client() as client:
           res = await providers.search_my_source(query, max_results, client)
       return _format_results(query, res, "my_source") if res else f"No my_source results for: {query}"

3. Füge einen Live-Testfall in tests/e2e_protocol.py hinzu.

4. Aktualisiere den Tools-Abschnitt der README.

Codestil

• Python 3.10+, async-first

• Type Hints überall; lass das Pydantic das MCP-JSON-Schema ableiten

• Jeder Provider umschließt den Netzwerkaufruf mit try/except und fällt auf [] zurück

• HTTP-Client pro Aufruf (_new_client()) — im stdio-Modus nicht über Aufrufe hinweg teilen

Mitwirken

Pull-Requests sind willkommen. Bevor du eine eröffnest:

1. Führe den e2e-Test gegen eine Live-Installation aus: .venv/bin/python tests/e2e_protocol.py

2. Füge einen Testfall für jedes neue Tool hinzu

3. Halte providers.py unabhängig von MCP-spezifischen Typen — es soll als normales Python-Modul wiederverwendbar bleiben

4. Füge keine Abhängigkeiten von Headless-Browsern oder Proxy-Rotation hinzu — das widerspricht der These des Projekts

Bei größeren Änderungen öffne zuerst ein Issue.

Lizenz

MIT — siehe LICENSE.

Danksagungen

• Basiert auf dem Model Context Protocol von Anthropic

• Verwendet Jina Reader für das saubere Abrufen von Seiten

• Such-APIs: Brave, Tavily, Wikipedia, arXiv, Crossref, Hacker News Algolia, Stack Exchange