grok-web-search-mcp

Idioma: English | 中文

Sobre el proyecto

Los agentes necesitan acceso en vivo a la web y a X con citas, no solo una respuesta de chat. Este proyecto envuelve las herramientas web_search y x_search del lado del servidor de xAI como una única herramienta MCP, de modo que hosts como Grok, Cursor o Claude Desktop puedan usarlas sin integrar la lógica de cliente de xAI.

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

Llamada upstream (simplificada):

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
    }
  ]
}

Objetivos de diseño:

• Una herramienta MCP, un único contrato de llamada — los modelos solo pueden pasar query / scope / recency / images

• Resultados ligeros — query / text / citations / sources_used (sin volcado bruto del upstream)

• URL base personalizable — https://api.x.ai/v1 oficial o proxies compatibles con OpenAI

• Entrada de visión opcional — adjunta URLs https o data URIs (las rutas locales son opt-in)

• Sin necesidad de PyPI — ejecútalo directamente desde GitHub con uvx --from git+...

Características

No incluido: enable_image_search (incrustación de galería de imágenes web). Usa images cuando tú proporciones una imagen; usa enable_image_understanding para imágenes en páginas visitadas y publicaciones de X.

Construido con

Related MCP server: WebQuest MCP

Cómo empezar

Requisitos previos

• Python 3.10+

• Una clave de API de xAI (o una clave para una puerta de enlace compatible)

• uv (recomendado para uvx desde GitHub)

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

Inicio rápido (uvx desde GitHub)

No se necesita clonar el repositorio para el uso diario con MCP:

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

Fija una rama, etiqueta o commit cuando necesites reproducibilidad:

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

Instalación para desarrollo local

1. Clona el repositorio:

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

2. Instala las dependencias:

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

3. Crea un archivo de entorno local:

   cp .env.example .env

4. Edita .env y establece al menos GROK_API_KEY (consulta Configuración).

Configuración

Mantén los secretos fuera de git. Siempre que sea posible, prefiere variables de entorno inyectadas por el host para las configuraciones MCP.

Uso

Ejecutar el servidor

Recomendado (desde GitHub):

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

Desde una copia local:

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

Ejemplo de proxy compatible:

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

Configuración del host MCP

Preferido: ejecutar desde GitHub con uvx (sin ruta local).

Hosts de estilo JSON (Cursor / Claude Desktop, etc.):

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

Configuración de usuario de Grok (~/.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"

Fija una ref (rama / etiqueta / commit):

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

Solo desarrollo local (ruta absoluta a una copia del repositorio):

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

Herramienta: web_search

Cada modelo del host debe usar el mismo contrato de cuatro claves. Los argumentos adicionales (model, reasoning_effort, system_prompt, filtros de dominio/handles) son rechazados. Los ajustes de calidad viven en variables de entorno para que el comportamiento de búsqueda no varíe entre modelos.

Ejemplo canónico:

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

El servidor entonces: normaliza query, inyecta un prompt de sistema fijo, aplica los filtros del operador desde el entorno, asigna recency a los límites de fecha de X y siempre usa el modelo / esfuerzo de razonamiento configurado.

images son partes input_image de la Responses API. Las rutas del sistema de archivos local están deshabilitadas por defecto. Esto no es "buscar imágenes de stock en la web."

Forma de la respuesta

Éxito (MCP isError: false, contenido estructurado):

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

El fallo es un error de herramienta a nivel de protocolo (isError: true) con un mensaje corto, por ejemplo Grok API error (401): Invalid API key. Las respuestas upstream incompletas o vacías también son errores, no éxitos silenciosos.

Intencionadamente no se devuelven: API key, model, base_url, JSON upstream sin procesar ni blobs de anotaciones (las URL se extraen únicamente en citations). Diagnostica la configuración fuera del resultado de la herramienta (env / ajustes MCP del host / registros de stderr).

Ejemplo de cliente Python

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())

Las llamadas reales consumen cuota de modelo y de búsqueda del lado del servidor. Las pruebas unitarias usan mocks y no acceden a la red.

Desarrollo

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

Estructura del proyecto:

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

Hoja de ruta

• Herramienta MCP web_search única y ligera

• Habilitar web_search y x_search del upstream por defecto

• Filtros de handle/fecha de X y comprensión de imágenes/vídeos

• Soporte de base_url / proxy personalizados

• Filtros de permitir/denegar dominios

• Entrada de imágenes multimodal opcional

• Instalar / ejecutar desde GitHub mediante uvx

• Errores a nivel de protocolo, reintentos, valores predeterminados de timeout/razonamiento

• Aislamiento de imágenes locales (deshabilitado por defecto)

• Contrato de llamada MCP canónico (query / scope / recency / images)

• Documentación/ejemplos opcionales de transporte HTTP Streamable

• Banco de pruebas de evaluación de conjunto golden para la calidad de búsqueda

Consulta los issues abiertos.

Contribuciones

Las contribuciones son bienvenidas.

1. Haz un fork del proyecto

2. Crea tu rama de características (git checkout -b feature/AmazingFeature)

3. Haz commit de tus cambios (git commit -m 'Add some AmazingFeature')

4. Haz push a la rama (git push origin feature/AmazingFeature)

5. Abre un Pull Request

Por favor, mantén la superficie de la herramienta ligera: prefiere una herramienta bien documentada a muchos wrappers finos.

Licencia

Distribuido bajo la Licencia MIT. Consulta LICENSE para más información.

Agradecimientos

• Best-README-Template

• xAI Web Search

• xAI X Search

• Model Context Protocol

• FastMCP

• uv