grok-search

English | 简体中文

Grok-with-Tavily MCP, proporciona capacidades de acceso a la red más completas para Claude Code

Este es un fork de GuDaStudio/GrokSearch (sunami-grok-search). El web_search del upstream subcontrata la búsqueda a una pasarela externa; al conectarse directamente a la API oficial api.x.ai no se realiza una búsqueda real, solo se hace que el modelo invente citas citation_card y sources_count sea siempre 0. Este fork utiliza las herramientas nativas web_search / x_search de la API Responses de xAI, las citas se leen de forma estructurada desde annotations[].url_citation, y los filtros de cuenta/tiempo de la búsqueda en X se exponen como parámetros. Los detalles de los cambios se encuentran en SUNAMI.md; para desplegar en otra máquina, basta con pasar el prompt de PROMPT.md al agente. A continuación se muestra la documentación original del upstream.

一、Descripción general

Grok Search MCP es un servidor MCP construido sobre FastMCP, con una arquitectura de doble motor: Grok se encarga de la búsqueda inteligente impulsada por IA, y Tavily se encarga del rastreo web de alta fidelidad y el mapeo de sitios, aprovechando las fortalezas de cada uno para proporcionar a clientes LLM como Claude Code / Cherry Studio capacidades completas de acceso a la red en tiempo real.

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

Características

• Doble motor: búsqueda Grok + rastreo/mapeo Tavily, colaboración complementaria

• Firecrawl como respaldo: cuando la extracción de Tavily falla, se degrada automáticamente a Firecrawl Scrape, con reintento automático para contenido vacío

• Interfaz compatible con OpenAI, compatible con cualquier sitio espejo de Grok

• Inyección automática de tiempo (detecta consultas relacionadas con el tiempo e inyecta el contexto de hora local)

• Desactivación con un clic de WebSearch/WebFetch oficiales de Claude Code, forzando el enrutamiento a esta herramienta

• Reintento inteligente (compatible con el análisis del encabezado Retry-After + retroceso exponencial)

• Monitoreo del proceso padre (en Windows, detecta automáticamente la salida del proceso padre para evitar procesos zombis)

Demostración de resultados

Tomamos como ejemplo la configuración de este MCP en cherry studio, mostrando cómo el modelo claude-opus-4.6 utiliza este proyecto para recopilar conocimiento externo y reducir la tasa de alucinaciones. Como se muestra arriba, para un experimento justo, activamos la herramienta de búsqueda integrada del modelo claude, sin embargo, opus 4.6 aún confía en su conocimiento interno y no consulta la documentación oficial de FastAPI para obtener los ejemplos más recientes. Como se muestra arriba, al activar el grok-search MCP, bajo las mismas condiciones experimentales, opus 4.6 realiza activamente múltiples búsquedas para obtener la documentación oficial, ofreciendo respuestas más fiables.

二、Instalación

Requisitos previos

• Python 3.10+

• uv (gestor de paquetes de Python recomendado)

• 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"

Para usuarios de Windows, se recomienda encarecidamente ejecutar este proyecto en WSL.

Instalación con un clic

Si ha instalado este proyecto anteriormente, use el siguiente comando para desinstalar la versión anterior del MCP.

claude mcp remove grok-search

Reemplace las variables de entorno en el siguiente comando con sus propios valores y ejecútelo. La interfaz de Grok debe ser compatible con el formato OpenAI; Tavily es opcional, y si no se configura, las herramientas web_fetch y web_map no estarán disponibles.

Usuarios de GuDa (recomendado)

Los usuarios de GuDa solo necesitan configurar GUDA_API_KEY para disfrutar del servicio completo; todas las direcciones de API se derivan automáticamente:

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"
  }
}'

Configuración personalizada

Si desea usar sus propios endpoints de API, puede configurar cada servicio por separado:

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"
  }
}'

En algunos entornos de red corporativa o con proxy, pueden aparecer errores similares a:

certificate verify failed self signed certificate in certificate chain

Puede agregar --native-tls a los argumentos de uvx para usar el almacén de certificados del sistema:

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" } }'

Además, puede configurar más variables de entorno en el campo env

Nota: después de configurar GUDA_API_KEY, GROK_API_URL/GROK_API_KEY/TAVILY_*/FIRECRAWL_* son todos opcionales; el sistema los deriva automáticamente de GUDA_BASE_URL. Las variables independientes establecidas explícitamente tienen mayor prioridad.

Verificar la instalación

claude mcp list

🍟 Después de que se muestre la conexión exitosa, recomendamos encarecidamente ingresar en la conversación de Claude

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

La herramienta modificará automáticamente el permissions.deny del archivo .claude/settings.json a nivel de proyecto, desactivando con un clic el WebSearch y WebFetch oficiales de Claude Code, forzando así a claude code a llamar a este proyecto para realizar búsquedas.

三、Introducción a las herramientas MCP

web_search — Búsqueda web con IA

Ejecuta búsquedas web impulsadas por IA a través de la API de Grok. Por defecto, solo devuelve el cuerpo de la respuesta de Grok y devuelve session_id para recuperar posteriormente las fuentes.

La salida de web_search no expande las fuentes, solo devuelve sources_count; las fuentes se almacenan en caché en el servidor según session_id y se pueden recuperar con get_sources.

Detecta automáticamente palabras clave relacionadas con el tiempo en la consulta (como "último", "hoy", "recent", etc.) e inyecta el contexto de hora local para mejorar la precisión de las búsquedas de actualidad.

Valor de retorno (diccionario estructurado):

• session_id: ID de sesión de esta consulta

• content: cuerpo de la respuesta de Grok (las fuentes se eliminan automáticamente)

• sources_count: cantidad de fuentes en caché

get_sources — Obtener fuentes

Obtiene todas las fuentes del web_search correspondiente mediante session_id.

Valor de retorno (diccionario estructurado):

• session_id

• sources_count

• sources: lista de fuentes (cada elemento contiene url, y puede incluir title/description/provider)

web_fetch — Extracción de contenido web

Obtiene el contenido completo de una página web mediante la API Tavily Extract, devolviéndolo en formato Markdown. Si Tavily falla, se degrada automáticamente a Firecrawl Scrape como respaldo.

web_map — Mapeo de estructura del sitio

Recorre la estructura del sitio mediante la API Tavily Map, descubre URL y genera un mapa del sitio.

get_config_info — Diagnóstico de configuración

No requiere parámetros. Muestra el estado de toda la configuración, prueba la conexión con la API de Grok, devuelve el tiempo de respuesta y la lista de modelos disponibles (la clave de API se enmascara automáticamente).

switch_model — Cambio de modelo

Después del cambio, la configuración se persiste en ~/.config/grok-search/config.json y se mantiene entre sesiones.

toggle_builtin_tools — Control de enrutamiento de herramientas

Modifica el permissions.deny del archivo .claude/settings.json a nivel de proyecto, desactivando con un clic el WebSearch y WebFetch oficiales de Claude Code.

search_planning — Planificación de búsqueda

Andamiaje de planificación de búsqueda estructurada (por fases, múltiples rondas), utilizado para generar un plan de búsqueda ejecutable antes de realizar búsquedas complejas.

四、Preguntas frecuentes

Licencia

MIT License

Si este proyecto le ha sido útil, ¡dé una estrella!