grok-search

English | 简体中文

Grok-with-Tavily MCP, bietet Claude Code erweiterte Netzwerkzugriffsfähigkeiten

Dies ist ein Fork von GuDaStudio/GrokSearch (sunami-grok-search). Das web_search des Upstreams lagert die Suche an ein Upstream-Gateway aus; bei direkter Verbindung zur offiziellen api.x.ai wird nicht wirklich gesucht, sondern das Modell erfindet lediglich citation_card-Zitate, und sources_count bleibt konstant 0. Dieser Fork nutzt stattdessen die nativen web_search / x_search-Tools der xAI Responses API, liest Zitate strukturiert aus annotations[].url_citation und stellt die Konto-/Zeitfilter der X-Suche als Parameter bereit. Details zu den Änderungen finden Sie in SUNAMI.md; für die Bereitstellung auf einem neuen Rechner genügt es, die Prompts aus PROMPT.md an den Agenten zu übergeben. Nachfolgend die ursprüngliche Upstream-Dokumentation.

1. Überblick

Grok Search MCP ist ein auf FastMCP basierender MCP-Server mit Zwei-Engine-Architektur: Grok übernimmt die KI-gestützte intelligente Suche, Tavily das hochpräzise Web-Scraping und Site-Mapping. Beide nutzen ihre jeweiligen Stärken, um LLM-Clients wie Claude Code / Cherry Studio vollständigen Echtzeit-Netzwerkzugriff zu bieten.

Claude ──MCP──► Grok Search Server
                  ├─ web_search  ───► Grok API（AI 搜索）
                  ├─ web_fetch   ───► Tavily Extract → Firecrawl Scrape（内容抓取，自动降级）
                  └─ web_map     ───► Tavily Map（站点映射）

Funktionen

• Zwei Engines: Grok-Suche + Tavily-Scraping/-Mapping, komplementär zusammenarbeitend

• Firecrawl als Fallback: Automatischer Fallback auf Firecrawl Scrape bei Tavily-Extraktionsfehlern, mit automatischem Retry bei leerem Inhalt

• OpenAI-kompatible Schnittstelle, unterstützt beliebige Grok-Mirror-Sites

• Automatische Zeitinjektion (erkennt zeitbezogene Suchanfragen und injiziert lokalen Zeitkontext)

• Ein-Klick-Deaktivierung der offiziellen WebSearch/WebFetch von Claude Code, erzwingt Routing über dieses Tool

• Intelligente Wiederholungsversuche (unterstützt Retry-After-Header-Parsing + exponentielles Backoff)

• Parent-Prozess-Überwachung (erkennt unter Windows automatisch den Exit des Parent-Prozesses, verhindert Zombie-Prozesse)

Ergebnis-Demo

Am Beispiel der Konfiguration dieses MCP in cherry studio zeigen wir, wie das Modell claude-opus-4.6 über dieses Projekt externes Wissen sammelt und die Halluzinationsrate senkt. Wie oben zu sehen, haben wir für ein faires Experiment das integrierte Suchtool des Claude-Modells aktiviert, dennoch vertraut opus 4.6 weiterhin seinem internen Allgemeinwissen und fragt nicht die offizielle FastAPI-Dokumentation ab, um aktuelle Beispiele zu erhalten. Wie oben zu sehen, ruft opus 4.6 bei aktiviertem grok-search MCP unter identischen Versuchsbedingungen proaktiv mehrere Suchen auf, um die offizielle Dokumentation abzurufen – die Antworten sind zuverlässiger.

2. Installation

Voraussetzungen

• Python 3.10+

• uv (empfohlener Python-Paketmanager)

• Claude Code

# Linux/macOS
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows PowerShell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Windows-Benutzern wird dringend empfohlen, dieses Projekt in WSL auszuführen.

Ein-Klick-Installation

Falls Sie dieses Projekt bereits installiert haben, entfernen Sie die alte MCP-Version mit dem folgenden Befehl.

claude mcp remove grok-search

Ersetzen Sie die Umgebungsvariablen im folgenden Befehl durch Ihre eigenen Werte und führen Sie ihn aus. Die Grok-Schnittstelle muss im OpenAI-kompatiblen Format vorliegen; Tavily ist optional – ohne Konfiguration sind die Tools web_fetch und web_map nicht verfügbar.

GuDa-Benutzer (empfohlen)

GuDa-Benutzer benötigen nur die Konfiguration von GUDA_API_KEY, um den vollständigen Service zu nutzen – alle API-Adressen werden automatisch abgeleitet:

claude mcp add-json grok-search --scope user '{
  "type": "stdio",
  "command": "uvx",
  "args": [
    "--from",
    "git+https://github.com/GuDaStudio/GrokSearch@grok-with-tavily",
    "grok-search"
  ],
  "env": {
    "GUDA_API_KEY": "your-guda-api-key"
  }
}'

Benutzerdefinierte Konfiguration

Für eigene API-Endpunkte können die einzelnen Dienste separat konfiguriert werden:

claude mcp add-json grok-search --scope user '{
  "type": "stdio",
  "command": "uvx",
  "args": [
    "--from",
    "git+https://github.com/GuDaStudio/GrokSearch@grok-with-tavily",
    "grok-search"
  ],
  "env": {
    "GROK_API_URL": "https://your-api-endpoint.com/v1",
    "GROK_API_KEY": "your-grok-api-key",
    "TAVILY_API_KEY": "tvly-your-tavily-key",
    "TAVILY_API_URL": "https://api.tavily.com"
  }
}'

In manchen Unternehmensnetzwerken oder Proxy-Umgebungen können Fehler wie die folgenden auftreten:

certificate verify failed self signed certificate in certificate chain

Sie können den Parameter --native-tls zu den uvx-Argumenten hinzufügen, um den Systemzertifikatsspeicher zu verwenden:

claude mcp add-json grok-search --scope user '{ "type": "stdio", "command": "uvx", "args": [ "--native-tls", "--from", "git+https://github.com/GuDaStudio/GrokSearch@grok-with-tavily", "grok-search" ], "env": { "GUDA_API_KEY": "your-guda-api-key" } }'

Darüber hinaus können Sie im Feld env weitere Umgebungsvariablen konfigurieren

Hinweis: Nach Konfiguration von GUDA_API_KEY sind GROK_API_URL/GROK_API_KEY/TAVILY_*/FIRECRAWL_* alle optional – das System leitet sie automatisch aus GUDA_BASE_URL ab. Explizit gesetzte unabhängige Variablen haben höhere Priorität.

Installation verifizieren

claude mcp list

🍟 Nach erfolgreicher Verbindungsanzeige empfehlen wir dringend, in den Claude-Chat einzugeben

调用 grok-search toggle_builtin_tools，关闭Claude Code's built-in WebSearch and WebFetch tools

Das Tool ändert automatisch permissions.deny in der projektbezogenen .claude/settings.json und deaktiviert mit einem Klick die offiziellen WebSearch- und WebFetch-Funktionen von Claude Code, wodurch Claude Code gezwungen wird, für die Suche dieses Projekt aufzurufen!

3. Vorstellung der MCP-Tools

web_search — KI-Netzwerksuche

Führt über die Grok-API eine KI-gestützte Netzwerksuche durch. Standardmäßig wird nur der Antworttext von Grok zurückgegeben, zusammen mit einer session_id für den späteren Abruf der Quellen.

web_search gibt die Quellen nicht erweitert aus, sondern nur sources_count; die Quellen werden serverseitig unter der session_id zwischengespeichert und können mit get_sources abgerufen werden.

Erkennt automatisch zeitbezogene Schlüsselwörter in der Suchanfrage (z. B. „neueste", „heute", „recent" usw.) und injiziert lokalen Zeitkontext, um die Genauigkeit zeitkritischer Suchen zu verbessern.

Rückgabewert (strukturiertes Wörterbuch):

• session_id: Sitzungs-ID dieser Abfrage

• content: Antworttext von Grok (Quellen wurden automatisch entfernt)

• sources_count: Anzahl der zwischengespeicherten Quellen

get_sources — Quellen abrufen

Ruft über die session_id alle Quellen der entsprechenden web_search-Abfrage ab.

Rückgabewert (strukturiertes Wörterbuch):

• session_id

• sources_count

• sources: Quellenliste (jeder Eintrag enthält url, ggf. title/description/provider)

web_fetch — Webinhalte abrufen

Ruft über die Tavily Extract API vollständige Webinhalte ab und gibt sie im Markdown-Format zurück. Bei Tavily-Fehlern erfolgt automatisch ein Fallback auf Firecrawl Scrape.

web_map — Seitenstruktur-Mapping

Durchläuft über die Tavily Map API die Website-Struktur, entdeckt URLs und erstellt eine Sitemap.

get_config_info — Konfigurationsdiagnose

Benötigt keine Parameter. Zeigt alle Konfigurationsstatus, testet die Grok-API-Verbindung, gibt Antwortzeit und Liste verfügbarer Modelle zurück (API-Schlüssel werden automatisch maskiert).

switch_model — Modellwechsel

Nach dem Wechsel wird die Konfiguration dauerhaft in ~/.config/grok-search/config.json gespeichert und bleibt über Sitzungen hinweg erhalten.

toggle_builtin_tools — Tool-Routing-Steuerung

Ändert permissions.deny in der projektbezogenen .claude/settings.json und deaktiviert mit einem Klick die offiziellen WebSearch- und WebFetch-Funktionen von Claude Code.

search_planning — Suchplanung

Strukturiertes Suchplanungs-Gerüst (phasenbasiert, mehrstufig), um vor der Ausführung komplexer Suchen zunächst einen ausführbaren Suchplan zu erstellen.

4. Häufig gestellte Fragen

Lizenz

MIT License

Wenn Ihnen dieses Projekt hilft, geben Sie ihm bitte einen Star!