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/v1oder OpenAI-kompatible ProxysOptionale 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
Funktion | Hinweise |
Live-Websuche | Grok erstellt eine Antwort mit Quellen-URLs |
Live-X-Suche | Standardmäßig enthalten; mit |
X-Filter | Behandelt Erlaubnis-/Verbotslisten (max. 20, |
Domain-Filter | Erlaubnisliste oder Verbotsliste (max. 5, sich gegenseitig ausschließend; Schema/Pfad entfernt) |
Medienverständnis bei der Suche | Bilder auf Webseiten und X-Beiträgen; Videos auf X-Beiträgen |
Client-Bildeingabe | Optionale |
Schlanke JSON-Ausgabe | Kein |
Protokollfehler | Upstream-/Validierungsfehler setzen MCP |
Wiederholungen | 429 / 502 / 503 / 504 und Transport-Timeouts, mit Backoff |
Proxy-freundlich |
|
GitHub-Installation |
|
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
uvxvon GitHub)
# optional: install uv
curl -LsSf https://astral.sh/uv/install.sh | shSchnellstart (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-mcpPinnen 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-mcpLokale Entwicklungsinstallation
Klonen Sie das Repository:
git clone https://github.com/NakanoSanku/grok-web-search-mcp.git cd grok-web-search-mcpInstallieren Sie die Abhängigkeiten:
uv sync # or: pip install -e ".[dev]"Erstellen Sie eine lokale Env-Datei:
cp .env.example .envBearbeiten Sie
.envund setzen Sie mindestensGROK_API_KEY(siehe Konfiguration).
Konfiguration
Variable | Erforderlich | Standard | Beschreibung |
| Ja | — | Akzeptiert auch |
| Nein |
| Auch |
| Nein |
| Auch |
| Nein |
| Anfrage-Timeout in Sekunden (1–3600). Hohes Reasoning + Suche können Minuten dauern |
| Nein |
| TCP/TLS-Verbindungs-Timeout (durch |
| Nein |
| Bilder auf durchsuchten Seiten und X-Beiträgen analysieren |
| Nein |
| Standard-Denklänge: |
| Nein |
| Erlaubt |
| Nein | cwd | Verzeichnis-Einschränkung für lokale Bilder, wenn aktiviert |
| Nein |
| Wiederholungen bei 429/5xx/Timeouts (0–8) |
| Nein |
|
|
| Nein |
| Videos in X-Beiträgen analysieren (nur Operator; kein Tool-Argument) |
| Nein | — | Web-Erlaubnisliste des Operators (max. 5). Aufrufer können dies nicht festlegen |
| Nein | — | Web-Verbotsliste des Operators (max. 5) |
| Nein | — | X-Handle-Erlaubnisliste des Operators (max. 20) |
| Nein | — | X-Handle-Verbotsliste des Operators (max. 20) |
| Nein | — | Zusätzliche Regeln, die an den servereigenen System-Prompt angehängt werden |
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-mcpAus 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_mcpBeispiel 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-mcpMCP-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 = trueTool: 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.
Parameter | Typ | Beschreibung |
| string | Erforderlich. Eine Frage in natürlicher Sprache, 2–600 Zeichen. Keine Stichwortliste ( |
|
| Standard |
|
| Standard |
| string[]? | Optionale Bild-URLs (http(s) / Data-URI, max. 5). Nur wenn der Benutzer ein Bild bereitgestellt hat. |
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 liveProjektstruktur:
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-ToolUpstream-
web_searchundx_searchstandardmäßig aktivierenX-Handle-/Datumsfilter und Bild-/Video-Verständnis
Unterstützung für benutzerdefinierte
base_url/ ProxyDomain-Allow-/Deny-Filter
Optionale multimodale Bildeingabe
Installation / Ausführung von GitHub über
uvxProtokollfehler, 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.
Forke das Projekt
Erstelle deinen Feature-Branch (
git checkout -b feature/AmazingFeature)Commite deine Änderungen (
git commit -m 'Add some AmazingFeature')Pushe den Branch (
git push origin feature/AmazingFeature)Ö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
Available Tools
1 toolweb_searchA
Live web and X search via Grok. Returns ok, text (answer), citations (URL list). Optional images: public URL, data:image/...;base64,..., or local file path (max 5) to ask about a picture while searching. Supports web domain filters, X handle/date filters, and reasoning_effort (low/medium/high). Image understanding applies to browsed pages and X posts; video understanding applies to X posts only.
Inputs: query (required), model, images, to_date, +10 more. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 1 tool
Only one tool exists, so there is no possibility of confusion or overlap with other tools.
With a single tool, naming consistency is inherently perfect as there is no pattern to break.
A single tool is slightly minimal but reasonably scoped for a focused web search server, as the tool itself is comprehensive.
The tool covers web search, X search, image understanding, domain and date filters, and reasoning effort, leaving no obvious gaps for its stated purpose.
Maintenance
Related MCP Connectors
Web search API and MCP server for developers building AI agents.
Live AI-native web search with citations. One tool for every MCP client. Flat per-request pricing.
Docs: https://docs.keenable.ai/mcp-server Keenable is a free, remote MCP server that gives agents access to the web index. Search the web with ranked results and date/site filters, then fetch any indexed page as clean markdown. Works out of the box with no account or API key.
Search, read, and act on the web. The Stophy MCP server for agents.
Related MCP Servers
- AlicenseAqualityBmaintenanceAn MCP server that provides real-time web search and X (Twitter) search capabilities via the xAI API.239 npmMIT
- AlicenseNot gradedqualityDmaintenanceA Model Context Protocol server that exposes powerful web search and scraping tools to AI agents and MCP-compatible clients.Apache 2.0
- AlicenseAqualityCmaintenanceMCP server for live X/Twitter and web search, driven by your locally logged-in Grok CLI and leveraging your X Premium or SuperGrok subscription quota.31MIT
- FlicenseNot gradedqualityDmaintenanceMCP server providing web search, news search, and X/Twitter search capabilities via HTTP or stdio.-