Grok Search

Búsqueda y análisis exhaustivos en la web, noticias y redes sociales utilizando la API de Grok de xAI.

GitHub
18
Prueba este MCPPatrocinado

Documentación

Servidor MCP Mejorado de Grok Search

Un servidor MCP (Model Context Protocol) robusto que proporciona capacidades integrales de búsqueda web y análisis utilizando la API de Grok de xAI.

Características

🔍 Capacidades de Búsqueda

  • Búsqueda Web: Busca contenido web general utilizando la búsqueda impulsada por IA de Grok
  • Búsqueda de Noticias: Busca noticias recientes y eventos actuales con análisis de línea de tiempo
  • Búsqueda en Twitter/X: Busca publicaciones en redes sociales con análisis de sentimiento
  • Filtrado por Rango de Fechas: Busca dentro de períodos de tiempo específicos

📊 Modos de Análisis

  • Modo Básico: Resultados de búsqueda tradicionales con títulos, fragmentos y URL
  • Modo Integral: Análisis enriquecido que incluye:
    • Líneas de tiempo detalladas de eventos
    • Citas directas con atribución completa
    • Múltiples perspectivas y puntos de vista
    • Contexto histórico e implicaciones
    • Estado de verificación de hechos
    • Categorización de hallazgos clave

🛡️ Características de Fiabilidad

  • Lógica de Reintentos: Reintento automático con retroceso exponencial para solicitudes fallidas
  • Tiempos de Espera de Solicitud: Tiempos de espera configurables para evitar bloqueos
  • Manejo de Errores Elegante: Respuestas de error integrales con contexto detallado
  • Monitoreo de Salud: Verificaciones de salud integradas y métricas de rendimiento
  • Caché: Caché inteligente para análisis integrales
  • Validación de Entrada: Saneamiento y validación mejorados de todas las entradas

🔧 Características Técnicas

  • Compatible con NPX: Instalación y uso fáciles a través de NPX
  • Protocolo MCP: Compatibilidad total con clientes MCP como Claude Desktop
  • Registro Estructurado: Registro integral para depuración y monitoreo
  • Métricas de Rendimiento: Seguimiento de solicitudes y monitoreo de tasa de éxito

Instalación

Proceso Simple en 3 Pasos

git clone https://github.com/stat-guy/grok-search-mcp.git
cd grok-search-mcp
npm install -g .

Verificar Instalación

Prueba que la instalación funcionó:

npx grok-search-mcp --help

Indicador de éxito: Si ves Grok Search MCP Server running on stdio, ¡tu instalación está lista!

Alternativa: Uso con NPX

npx grok-search-mcp

Configuración

1. Obtén tu Clave de API de xAI

  1. Visita el Portal de Desarrolladores de xAI
  2. Crea una cuenta o inicia sesión
  3. Genera tu clave de API
  4. Copia la clave de API para el siguiente paso

2. Configurar Variable de Entorno

Establece tu clave de API de xAI como variable de entorno:

export XAI_API_KEY="your-api-key-here"

O crea un archivo .env en tu proyecto:

XAI_API_KEY=your-api-key-here

3. Configurar Claude Desktop

Agrega el servidor a tu archivo de configuración de Claude Desktop:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "grok-search": {
      "command": "npx",
      "args": ["grok-search-mcp"],
      "env": {
        "XAI_API_KEY": "your-api-key-here"
      }
    }
  }
}

Herramientas Disponibles

grok_search

Herramienta de búsqueda de propósito general con tipos de búsqueda y modos de análisis configurables.

Parámetros:

  • query (obligatorio): La consulta de búsqueda
  • search_type (opcional): "web", "news" o "general" (predeterminado: "web")
  • analysis_mode (opcional): "basic" o "comprehensive" (predeterminado: "basic")
  • max_results (opcional): Número máximo de resultados (1-20, predeterminado: 10)
  • from_date (opcional): Fecha de inicio en formato YYYY-MM-DD
  • to_date (opcional): Fecha de fin en formato YYYY-MM-DD

Ejemplo de Modo Básico:

{
  "query": "latest AI developments",
  "search_type": "news",
  "max_results": 5
}

Ejemplo de Modo Integral:

{
  "query": "US Iran conflict 2025",
  "search_type": "news",
  "analysis_mode": "comprehensive",
  "max_results": 10,
  "from_date": "2025-06-20",
  "to_date": "2025-06-24"
}

grok_web_search

Busca contenido web general con soporte de análisis integral.

Parámetros:

  • query (obligatorio): La consulta de búsqueda web
  • analysis_mode (opcional): "basic" o "comprehensive" (predeterminado: "basic")
  • max_results (opcional): Número máximo de resultados (1-20, predeterminado: 10)
  • from_date (opcional): Fecha de inicio en formato YYYY-MM-DD
  • to_date (opcional): Fecha de fin en formato YYYY-MM-DD

grok_news_search

Busca noticias recientes con análisis integral de línea de tiempo y contexto.

Parámetros:

  • query (obligatorio): La consulta de búsqueda de noticias
  • analysis_mode (opcional): "basic" o "comprehensive" (predeterminado: "basic")
  • max_results (opcional): Número máximo de resultados (1-20, predeterminado: 10)
  • from_date (opcional): Fecha de inicio en formato YYYY-MM-DD
  • to_date (opcional): Fecha de fin en formato YYYY-MM-DD

grok_twitter

Busca publicaciones de Twitter/X con análisis de redes sociales.

Parámetros:

  • query (obligatorio): La consulta de búsqueda para tweets
  • handles (opcional): Matriz de identificadores de Twitter para filtrar (sin el símbolo @)
  • analysis_mode (opcional): "basic" o "comprehensive" (predeterminado: "basic")
  • max_results (opcional): Número máximo de resultados (1-20, predeterminado: 10)
  • from_date (opcional): Fecha de inicio en formato YYYY-MM-DD
  • to_date (opcional): Fecha de fin en formato YYYY-MM-DD

health_check

Verifica la salud del servidor y el estado de conectividad de la API.

Parámetros: Ninguno

Formatos de Respuesta

Respuesta de Modo Básico

{
  "query": "search query",
  "analysis_mode": "basic",
  "results": [
    {
      "title": "Result Title",
      "snippet": "Brief description or excerpt",
      "url": "https://example.com",
      "source": "source-name",
      "published_date": "2025-06-24",
      "author": "Author Name",
      "citation_url": "https://example.com",
      "citation_metadata": {
        "domain": "example.com",
        "is_secure": true
      }
    }
  ],
  "citations": ["https://example.com"],
  "summary": "Brief overview of findings",
  "total_results": 5,
  "search_time": "2025-06-24T12:00:00.000Z",
  "source": "grok-live-search"
}

Respuesta de Modo Integral

{
  "query": "search query",
  "analysis_mode": "comprehensive",
  "comprehensive_analysis": "Detailed analysis with context and implications...",
  "key_findings": [
    {
      "category": "main_story",
      "title": "Primary Development",
      "content": "Detailed explanation with specifics",
      "sources": ["https://source1.com", "https://source2.com"],
      "confidence": "high"
    }
  ],
  "timeline": [
    {
      "date": "2025-06-21",
      "event": "Initial event occurred",
      "source": "News Source",
      "significance": "This marked the beginning of..."
    }
  ],
  "direct_quotes": [
    {
      "quote": "This is an exact quote from the source",
      "speaker": "Official Name",
      "context": "During a press conference on Monday",
      "source_url": "https://source.com",
      "significance": "This statement clarifies the position..."
    }
  ],
  "related_context": "Historical background and connections...",
  "multiple_perspectives": [
    {
      "viewpoint": "Supporters",
      "content": "Analysis from this perspective",
      "sources": ["https://supporting-source.com"],
      "reasoning": "This group supports because..."
    }
  ],
  "implications": {
    "short_term": "Immediate consequences include...",
    "long_term": "Potential long-term impacts are...",
    "stakeholders_affected": ["Group 1", "Group 2"]
  },
  "verification_status": {
    "confirmed_facts": ["Verified information"],
    "unconfirmed_claims": ["Unverified claims"],
    "contradictory_information": ["Conflicting reports"]
  },
  "raw_results": [
    {
      "title": "Source Article",
      "snippet": "Brief description",
      "url": "https://example.com",
      "relevance_score": 9
    }
  ],
  "summary": "Executive summary of the entire analysis",
  "total_results": 10,
  "search_time": "2025-06-24T12:00:00.000Z",
  "source": "grok-comprehensive-analysis"
}

Configuración

Variables de Entorno

  • XAI_API_KEY (obligatorio): Tu clave de API de xAI
  • GROK_TIMEOUT (opcional): Tiempo de espera de solicitud en milisegundos (predeterminado: 30000)
  • GROK_MAX_RETRIES (opcional): Intentos máximos de reintento (predeterminado: 3)

Ejemplo de Configuración de Claude Desktop

{
  "mcpServers": {
    "grok-search": {
      "command": "npx",
      "args": ["grok-search-mcp"],
      "env": {
        "XAI_API_KEY": "your-api-key-here",
        "GROK_TIMEOUT": "45000",
        "GROK_MAX_RETRIES": "5"
      }
    }
  }
}

Manejo de Errores

El servidor incluye manejo integral de errores con respuestas de error estandarizadas:

  • Clave de API Inválida: Degradación elegante con mensajes de error claros
  • Consulta Vacía: Validación mejorada con retroalimentación detallada
  • Límites de Tasa de API: Reintento automático con retroceso exponencial
  • Problemas de Red: Manejo de errores de conexión con lógica de reintento
  • Problemas de Tiempo de Espera: Tiempos de espera configurables con informes de error claros
  • Análisis JSON: Múltiples estrategias de análisis con manejo de respaldo

Formato de Respuesta de Error

{
  "error": "Detailed error message",
  "status": "failed",
  "query": "original query",
  "search_type": "web",
  "analysis_mode": "basic",
  "timestamp": "2025-06-24T12:00:00.000Z",
  "request_id": "req_1234567890_abc123"
}

Características de Rendimiento

Caché

  • Caché de Análisis Integral: Caché inteligente para análisis integrales costosos
  • Gestión de TTL: Expiración de caché configurable (predeterminado: 30 minutos)
  • Gestión de Memoria: Límites automáticos de tamaño de caché para prevenir problemas de memoria

Monitoreo

  • Verificaciones de Salud: Monitoreo de salud integrado con informes de estado detallados
  • Métricas de Rendimiento: Seguimiento de solicitudes, tasas de éxito y análisis de tiempos
  • Registro Estructurado: Registros en formato JSON para fácil análisis y monitoreo

Fiabilidad

  • Lógica de Reintentos: Retroceso exponencial para fallas transitorias
  • Interrupción de Circuito: Degradación elegante cuando la API no está disponible
  • Saneamiento de Entrada: Validación y limpieza integral de entradas
  • Recuperación de Errores: Múltiples estrategias de análisis JSON para manejo robusto de respuestas

Solución de Problemas

Problemas Comunes

  1. "El servicio de API no está disponible"

    • Verifica si XAI_API_KEY está configurada correctamente
    • Verifica que tu clave de API sea válida y esté activa
    • Usa la herramienta health_check para diagnosticar la conectividad de la API

  2. "Tiempo de espera de solicitud excedido después de Xms"

    • Aumenta la variable de entorno GROK_TIMEOUT
    • Verifica tu conexión a internet
    • Considera usar el modo básico para respuestas más rápidas

  3. "Consulta de búsqueda demasiado larga"

    • Las consultas están limitadas a 1000 caracteres
    • Divide consultas complejas en partes más pequeñas

  4. Resultados vacíos o deficientes en modo integral

    • Prueba con diferentes formulaciones de consulta
    • Usa el modo básico para búsquedas simples
    • Verifica si el tema tiene suficiente cobertura reciente

Monitoreo de Salud

Usa la herramienta health_check para obtener estado detallado:

{
  "tool": "health_check"
}

Ejemplo de respuesta de salud:

{
  "server_healthy": true,
  "api_healthy": true,
  "uptime_ms": 3600000,
  "total_requests": 150,
  "error_count": 3,
  "success_rate": "98.00%",
  "api_details": {
    "hasApiKey": true,
    "cacheSize": 12
  }
}

Depuración

El servidor proporciona registro estructurado. Monitorea la salida de stderr para registros detallados:

npx grok-search-mcp 2>debug.log

Pruebas

Ejecuta el conjunto de pruebas para verificar la funcionalidad:

# With API key
XAI_API_KEY=your-key npm test

# Basic functionality test (may skip API calls)
npm test

Ejemplos de Uso

Búsqueda Básica de Noticias

{
  "query": "latest technology news",
  "search_type": "news",
  "max_results": 5
}

Análisis Integral

{
  "query": "climate change policy 2025",
  "analysis_mode": "comprehensive",
  "search_type": "news",
  "from_date": "2025-01-01",
  "max_results": 15
}

Análisis de Twitter con Identificadores Específicos

{
  "query": "AI developments",
  "handles": ["elonmusk", "OpenAI", "AnthropicAI"],
  "analysis_mode": "comprehensive",
  "max_results": 10
}

Búsqueda Web Filtrada por Fecha

{
  "query": "quantum computing breakthroughs",
  "search_type": "web",
  "from_date": "2025-06-01",
  "to_date": "2025-06-24",
  "max_results": 8
}

Límites de la API

  • Los límites de tasa dependen de tu plan de API de xAI
  • Monitorea el uso a través del Portal de Desarrolladores de xAI
  • El modo integral usa más tokens que el modo básico
  • El caché ayuda a reducir el uso de la API para consultas repetidas

Licencia

Este servidor MCP está licenciado bajo la Licencia MIT. Esto significa que eres libre de usar, modificar y distribuir el software, sujeto a los términos y condiciones de la Licencia MIT. Para más detalles, consulta el archivo LICENSE en el repositorio del proyecto.

Soporte

Para problemas y solicitudes de funciones, crea un issue en el repositorio.

Contribuciones

  1. Haz un fork del repositorio
  2. Crea una rama de características
  3. Realiza tus cambios
  4. Agrega pruebas para la nueva funcionalidad
  5. Actualiza la documentación
  6. Envía una solicitud de extracción

Registro de Cambios

Versión 2.0.0 (Mejorada)

  • ✅ Se agregó el modo de análisis integral con contexto enriquecido
  • ✅ Se implementó la extracción de líneas de tiempo y citas directas
  • ✅ Se agregó el análisis de múltiples perspectivas
  • ✅ Se mejoró el manejo de errores con lógica de reintentos
  • ✅ Se agregó caché inteligente para análisis integrales
  • ✅ Se implementó monitoreo de salud y métricas de rendimiento
  • ✅ Se agregó sistema de registro estructurado
  • ✅ Se mejoró la validación y saneamiento de entradas
  • ✅ Se agregaron tiempos de espera y configuraciones de reintento configurables
  • ✅ Se mejoró el análisis JSON con múltiples estrategias de respaldo