grok-web-search-mcp

Sprache: Englisch | 中文

Über das Projekt

Agenten benötigen Live-Web- und X-Zugriff mit Quellenangaben, nicht nur eine Chat-Antwort. Dieses Projekt kapselt die serverseitigen Tools web_search und x_search von xAI als ein einziges MCP-Tool, sodass Hosts wie Grok, Cursor oder Claude Desktop sie aufrufen können, ohne xAI-Clientlogik einzubetten.

Repository: https://github.com/NakanoSanku/grok-web-search-mcp

Upstream-Aufruf (vereinfacht):

POST {base_url}/responses
Authorization: Bearer <api_key>
Content-Type: application/json

{
  "model": "grok-4.5",
  "input": [{"role": "user", "content": "<query>"}],
  "tools": [
    {"type": "web_search", "enable_image_understanding": true},
    {
      "type": "x_search",
      "allowed_x_handles": ["xai"],
      "from_date": "2025-10-01",
      "to_date": "2025-10-10",
      "enable_image_understanding": true,
      "enable_video_understanding": true
    }
  ]
}

Designziele:

• Ein MCP-Tool, ein Aufrufvertrag – Modelle dürfen nur query / scope / recency / images übergeben.

• Schlanke Ergebnisse – query / text / citations / sources_used (kein roher Upstream-Dump)

• Benutzerdefinierte Basis-URL – offizielle https://api.x.ai/v1 oder OpenAI-kompatible Proxys

• Optionale Bildeingabe – HTTPS-URLs oder Data-URIs anhängen (lokale Pfade nur auf Wunsch)

• Kein PyPI erforderlich – direkt von GitHub mit uvx --from git+... ausführen

Funktionen

Nicht enthalten: enable_image_search (Einbettung von Web-Bildergalerien). Verwenden Sie images, wenn Sie ein Bild bereitstellen; verwenden Sie enable_image_understanding für Bilder auf durchsuchten Seiten und X-Beiträgen.

Erstellt mit

Related MCP server: WebQuest MCP

Erste Schritte

Voraussetzungen

• Python 3.10+

• Ein xAI-API-Schlüssel (oder ein Schlüssel für ein kompatibles Gateway)

• uv (empfohlen für uvx von GitHub)

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

Schnellstart (uvx von GitHub)

Für den täglichen MCP-Einsatz ist kein lokaler Klon erforderlich:

export GROK_API_KEY=xai-...
uvx --from git+https://github.com/NakanoSanku/grok-web-search-mcp.git grok-web-search-mcp

Pinnen Sie einen Branch, Tag oder Commit, wenn Sie Reproduzierbarkeit benötigen:

uvx --from git+https://github.com/NakanoSanku/grok-web-search-mcp.git@main grok-web-search-mcp
# uvx --from git+https://github.com/NakanoSanku/grok-web-search-mcp.git@v0.3.0 grok-web-search-mcp

Lokale Entwicklungsinstallation

1. Klonen Sie das Repository:

   git clone https://github.com/NakanoSanku/grok-web-search-mcp.git
   cd grok-web-search-mcp

2. Installieren Sie die Abhängigkeiten:

   uv sync
   # or: pip install -e ".[dev]"

3. Erstellen Sie eine lokale Env-Datei:

   cp .env.example .env

4. Bearbeiten Sie .env und setzen Sie mindestens GROK_API_KEY (siehe Konfiguration).

Konfiguration

Halten Sie Geheimnisse aus Git heraus. Bevorzugen Sie nach Möglichkeit vom Host injizierte Umgebungsvariablen für MCP-Konfigurationen.

Verwendung

Server ausführen

Empfohlen (von GitHub):

export GROK_API_KEY=xai-...
uvx --from git+https://github.com/NakanoSanku/grok-web-search-mcp.git grok-web-search-mcp

Aus einem lokalen Checkout:

export GROK_API_KEY=xai-...
# Windows PowerShell: $env:GROK_API_KEY="xai-..."

uv run grok-web-search-mcp
# or
uv run python -m grok_web_search_mcp

Beispiel für einen kompatiblen Proxy:

export GROK_API_KEY=sk-xxx
export GROK_BASE_URL=http://127.0.0.1:8317/v1
export GROK_MODEL=grok-4.5
uvx --from git+https://github.com/NakanoSanku/grok-web-search-mcp.git grok-web-search-mcp

MCP-Host-Konfiguration

Bevorzugt: von GitHub mit uvx ausführen (kein lokaler Pfad).

JSON-basierte Hosts (Cursor / Claude Desktop usw.):

{
  "mcpServers": {
    "grok-web-search": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/NakanoSanku/grok-web-search-mcp.git",
        "grok-web-search-mcp"
      ],
      "env": {
        "GROK_API_KEY": "xai-your-key",
        "GROK_BASE_URL": "https://api.x.ai/v1",
        "GROK_MODEL": "grok-4.5"
      }
    }
  }
}

Grok-Benutzerkonfiguration (~/.grok/config.toml):

[mcp_servers.grok-web-search]
command = "uvx"
args = [
  "--from",
  "git+https://github.com/NakanoSanku/grok-web-search-mcp.git",
  "grok-web-search-mcp",
]
enabled = true

[mcp_servers.grok-web-search.env]
GROK_API_KEY = "xai-your-key"
GROK_BASE_URL = "https://api.x.ai/v1"
GROK_MODEL = "grok-4.5"

Einen Ref pinnen (Branch / Tag / Commit):

args = [
  "--from",
  "git+https://github.com/NakanoSanku/grok-web-search-mcp.git@main",
  "grok-web-search-mcp",
]

Nur für lokale Entwicklung (absoluter Pfad zu einem Checkout):

[mcp_servers.grok-web-search]
command = "uv"
args = [
  "run",
  "--directory",
  "/absolute/path/to/grok-web-search-mcp",
  "grok-web-search-mcp",
]
enabled = true

Tool: web_search

Jedes Host-Modell muss denselben Vier-Schlüssel-Vertrag verwenden. Zusätzliche Argumente (model, reasoning_effort, system_prompt, Domain-/Handle-Filter) werden abgelehnt. Qualitätsregler liegen in Umgebungsvariablen, damit das Suchverhalten zwischen Modellen nicht abweicht.

Kanonisches Beispiel:

{ "query": "What is xAI's latest valuation?" }

Der Server führt dann Folgendes aus: normalisiert query, fügt einen festen System-Prompt ein, wendet Operator-Filter aus der Umgebung an, bildet recency auf X-Datumsgrenzen ab und verwendet immer das konfigurierte Modell / Reasoning-Effort.

images sind input_image-Teile der Responses API. Lokale Dateisystempfade sind standardmäßig deaktiviert. Dies ist keine „Suche im Web nach Stockbildern“.

Antwortformat

Erfolg (MCP isError: false, strukturierter Inhalt):

{
  "query": "What is xAI?",
  "text": "...",
  "citations": [{"url": "https://x.ai", "title": "xAI"}],
  "sources_used": ["web", "x"],
  "scope": "all",
  "recency": "any"
}

Ein Fehler ist ein Protokollfehler des Tools (isError: true) mit einer kurzen Meldung, zum Beispiel Grok API error (401): Invalid API key. Unvollständige oder leere Upstream-Antworten sind ebenfalls Fehler und kein stiller Erfolg.

Absichtlich nicht zurückgegeben: API-Schlüssel, model, base_url, rohes Upstream-JSON oder Annotations-Blobs (URLs werden ausschließlich in citations übernommen). Diagnostiziere die Konfiguration außerhalb des Tool-Ergebnisses (Env / Host-MCP-Einstellungen / stderr-Logs).

Python-Client-Beispiel

import asyncio
from grok_web_search_mcp.client import GrokWebSearchClient
from grok_web_search_mcp.config import Settings

async def main():
    async with GrokWebSearchClient(Settings.from_env()) as client:
        result = await client.web_search("What is xAI?")
        print(result.to_dict())

asyncio.run(main())

Echte Aufrufe verbrauchen Modell- und serverseitiges Suchkontingent. Unit-Tests verwenden Mocks und greifen nicht auf das Netzwerk zu.

Entwicklung

git clone https://github.com/NakanoSanku/grok-web-search-mcp.git
cd grok-web-search-mcp
uv sync --extra dev
uv run pytest
# live API (optional): GROK_LIVE=1 uv run pytest -m live

Projektstruktur:

src/grok_web_search_mcp/
  server.py    # MCP tool surface
  client.py    # Responses API client + image helpers
  config.py    # Environment settings
tests/

Roadmap

• Ein einziges schlankes web_search-MCP-Tool

• Upstream-web_search und x_search standardmäßig aktivieren

• X-Handle-/Datumsfilter und Bild-/Video-Verständnis

• Unterstützung für benutzerdefinierte base_url / Proxy

• Domain-Allow-/Deny-Filter

• Optionale multimodale Bildeingabe

• Installation / Ausführung von GitHub über uvx

• Protokollfehler, Wiederholungen, Timeout-/Reasoning-Standardwerte

• Lokales Image-Jail (standardmäßig deaktiviert)

• Kanonischer MCP-Aufrufvertrag (query / scope / recency / images)

• Optionale Streamable-HTTP-Transport-Dokumentation/-Beispiele

• Golden-Set-Evaluations-Harness für die Suchqualität

Siehe die offenen Issues.

Mitwirken

Beiträge sind willkommen.

1. Forke das Projekt

2. Erstelle deinen Feature-Branch (git checkout -b feature/AmazingFeature)

3. Commite deine Änderungen (git commit -m 'Add some AmazingFeature')

4. Pushe den Branch (git push origin feature/AmazingFeature)

5. Öffne einen Pull Request

Bitte halte die Tool-Oberfläche schlank: Bevorzuge ein gut dokumentiertes Tool gegenüber vielen dünnen Wrappern.

Lizenz

Verteilt unter der MIT-Lizenz. Siehe LICENSE für weitere Informationen.

Danksagungen

• Best-README-Template

• xAI Web Search

• xAI X Search

• Model Context Protocol

• FastMCP

• uv