Grok Search

Pesquisa e análise abrangentes da web, notícias e mídias sociais usando a API Grok da xAI.

GitHub
19
Experimente este MCPPatrocinado

Documentação

Servidor MCP Grok Search Aprimorado

Um servidor MCP (Model Context Protocol) robusto que fornece capacidades abrangentes de busca e análise na web usando a API Grok da xAI.

Recursos

🔍 Capacidades de Busca

  • Busca na Web: Busque conteúdo geral da web usando a busca com IA da Grok
  • Busca de Notícias: Busque notícias recentes e eventos atuais com análise de linha do tempo
  • Busca no Twitter/X: Busque postagens em redes sociais com análise de sentimento
  • Filtro por Intervalo de Datas: Busque dentro de períodos específicos

📊 Modos de Análise

  • Modo Básico: Resultados de busca tradicionais com títulos, trechos e URLs
  • Modo Abrangente: Análise rica incluindo:
    • Linhas do tempo detalhadas de eventos
    • Citações diretas com atribuição completa
    • Múltiplas perspectivas e pontos de vista
    • Contexto histórico e implicações
    • Status de verificação de fatos
    • Categorização de descobertas-chave

🛡️ Recursos de Confiabilidade

  • Lógica de Repetição: Repetição automática com backoff exponencial para solicitações com falha
  • Tempos de Espera de Solicitação: Tempos de espera configuráveis para evitar travamentos
  • Tratamento de Erros Elegante: Respostas de erro abrangentes com contexto detalhado
  • Monitoramento de Saúde: Verificações de saúde integradas e métricas de desempenho
  • Cache: Cache inteligente para análises abrangentes
  • Validação de Entrada: Saneamento e validação aprimorados de todas as entradas

🔧 Recursos Técnicos

  • Compatível com NPX: Instalação e uso fáceis via NPX
  • Protocolo MCP: Compatibilidade total com clientes MCP como Claude Desktop
  • Registro Estruturado: Registro abrangente para depuração e monitoramento
  • Métricas de Desempenho: Rastreamento de solicitações e monitoramento de taxa de sucesso

Instalação

Processo Simples em 3 Etapas

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

Verificar Instalação

Teste se a instalação funcionou:

npx grok-search-mcp --help

Indicador de sucesso: Se você vir Grok Search MCP Server running on stdio, sua instalação está pronta!

Alternativa: Uso via NPX

npx grok-search-mcp

Configuração

1. Obtenha Sua Chave de API da xAI

  1. Visite o xAI Developer Portal
  2. Crie uma conta ou faça login
  3. Gere sua chave de API
  4. Copie a chave de API para o próximo passo

2. Configure a Variável de Ambiente

Defina sua chave de API da xAI como uma variável de ambiente:

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

Ou crie um arquivo .env no seu projeto:

XAI_API_KEY=your-api-key-here

3. Configure o Claude Desktop

Adicione o servidor ao seu arquivo de configuração do 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"
      }
    }
  }
}

Ferramentas Disponíveis

grok_search

Ferramenta de busca de propósito geral com tipos de busca e modos de análise configuráveis.

Parâmetros:

  • query (obrigatório): A consulta de busca
  • search_type (opcional): "web", "news" ou "general" (padrão: "web")
  • analysis_mode (opcional): "basic" ou "comprehensive" (padrão: "basic")
  • max_results (opcional): Número máximo de resultados (1-20, padrão: 10)
  • from_date (opcional): Data de início no formato YYYY-MM-DD
  • to_date (opcional): Data de término no formato YYYY-MM-DD

Exemplo de Modo Básico:

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

Exemplo de Modo Abrangente:

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

Busque conteúdo geral da web com suporte a análise abrangente.

Parâmetros:

  • query (obrigatório): A consulta de busca na web
  • analysis_mode (opcional): "basic" ou "comprehensive" (padrão: "basic")
  • max_results (opcional): Número máximo de resultados (1-20, padrão: 10)
  • from_date (opcional): Data de início no formato YYYY-MM-DD
  • to_date (opcional): Data de término no formato YYYY-MM-DD

grok_news_search

Busque notícias recentes com análise abrangente de linha do tempo e contexto.

Parâmetros:

  • query (obrigatório): A consulta de busca de notícias
  • analysis_mode (opcional): "basic" ou "comprehensive" (padrão: "basic")
  • max_results (opcional): Número máximo de resultados (1-20, padrão: 10)
  • from_date (opcional): Data de início no formato YYYY-MM-DD
  • to_date (opcional): Data de término no formato YYYY-MM-DD

grok_twitter

Busque postagens do Twitter/X com análise de mídia social.

Parâmetros:

  • query (obrigatório): A consulta de busca para tweets
  • handles (opcional): Matriz de handles do Twitter para filtrar (sem o símbolo @)
  • analysis_mode (opcional): "basic" ou "comprehensive" (padrão: "basic")
  • max_results (opcional): Número máximo de resultados (1-20, padrão: 10)
  • from_date (opcional): Data de início no formato YYYY-MM-DD
  • to_date (opcional): Data de término no formato YYYY-MM-DD

health_check

Verifique a saúde do servidor e o status de conectividade da API.

Parâmetros: Nenhum

Formatos de Resposta

Resposta do 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"
}

Resposta do Modo Abrangente

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

Configuração

Variáveis de Ambiente

  • XAI_API_KEY (obrigatório): Sua chave de API da xAI
  • GROK_TIMEOUT (opcional): Tempo de espera da solicitação em milissegundos (padrão: 30000)
  • GROK_MAX_RETRIES (opcional): Número máximo de tentativas de repetição (padrão: 3)

Exemplo de Configuração do 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"
      }
    }
  }
}

Tratamento de Erros

O servidor inclui tratamento de erros abrangente com respostas de erro padronizadas:

  • Chave de API Inválida: Degradação elegante com mensagens de erro claras
  • Consulta Vazia: Validação aprimorada com feedback detalhado
  • Limites de Taxa da API: Repetição automática com backoff exponencial
  • Problemas de Rede: Tratamento de erros de conexão com lógica de repetição
  • Problemas de Tempo de Espera: Tempos de espera configuráveis com relatórios de erro claros
  • Análise JSON: Múltiplas estratégias de análise com tratamento de fallback

Formato de Resposta de Erro

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

Recursos de Desempenho

Cache

  • Cache de Análise Abrangente: Cache inteligente para análises abrangentes caras
  • Gerenciamento de TTL: Expiração de cache configurável (padrão: 30 minutos)
  • Gerenciamento de Memória: Limites automáticos de tamanho do cache para evitar problemas de memória

Monitoramento

  • Verificações de Saúde: Monitoramento de saúde integrado com relatórios de status detalhados
  • Métricas de Desempenho: Rastreamento de solicitações, taxas de sucesso e análise de tempo
  • Registro Estruturado: Logs formatados em JSON para fácil análise e monitoramento

Confiabilidade

  • Lógica de Repetição: Backoff exponencial para falhas transitórias
  • Interrupção de Circuito: Degradação elegante quando a API está indisponível
  • Saneamento de Entrada: Validação e limpeza abrangentes de entrada
  • Recuperação de Erros: Múltiplas estratégias de análise JSON para tratamento robusto de respostas

Solução de Problemas

Problemas Comuns

  1. "O serviço da API não está disponível"

    • Verifique se XAI_API_KEY está definida corretamente
    • Verifique se sua chave de API é válida e ativa
    • Use a ferramenta health_check para diagnosticar a conectividade da API

  2. "Tempo de espera da solicitação excedido após Xms"

    • Aumente a variável de ambiente GROK_TIMEOUT
    • Verifique sua conexão com a internet
    • Considere usar o modo básico para respostas mais rápidas

  3. "Consulta de busca muito longa"

    • As consultas são limitadas a 1000 caracteres
    • Divida consultas complexas em partes menores

  4. Resultados vazios ou ruins no modo abrangente

    • Tente formulações de consulta diferentes
    • Use o modo básico para buscas simples
    • Verifique se o tópico tem cobertura recente suficiente

Monitoramento de Saúde

Use a ferramenta health_check para obter status detalhado:

{
  "tool": "health_check"
}

Exemplo de resposta de saúde:

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

Depuração

O servidor fornece registro estruturado. Monitore a saída stderr para logs detalhados:

npx grok-search-mcp 2>debug.log

Testes

Execute a suíte de testes para verificar a funcionalidade:

# With API key
XAI_API_KEY=your-key npm test

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

Exemplos de Uso

Busca Básica de Notícias

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

Análise Abrangente

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

Análise do Twitter com Handles Específicos

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

Busca na Web com Filtro de Data

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

Limites da API

  • Os limites de taxa dependem do seu plano da API xAI
  • Monitore o uso através do xAI Developer Portal
  • O modo abrangente usa mais tokens do que o modo básico
  • O cache ajuda a reduzir o uso da API para consultas repetidas

Licença

Este servidor MCP é licenciado sob a Licença MIT. Isso significa que você é livre para usar, modificar e distribuir o software, sujeito aos termos e condições da Licença MIT. Para mais detalhes, consulte o arquivo LICENSE no repositório do projeto.

Suporte

Para problemas e solicitações de recursos, crie uma issue no repositório.

Contribuindo

  1. Faça um fork do repositório
  2. Crie um branch de recurso
  3. Faça suas alterações
  4. Adicione testes para novas funcionalidades
  5. Atualize a documentação
  6. Envie um pull request

Registro de Alterações

Versão 2.0.0 (Aprimorada)

  • ✅ Adicionado modo de análise abrangente com contexto rico
  • ✅ Implementada extração de linha do tempo e citações diretas
  • ✅ Adicionada análise de múltiplas perspectivas
  • ✅ Aprimorado tratamento de erros com lógica de repetição
  • ✅ Adicionado cache inteligente para análises abrangentes
  • ✅ Implementado monitoramento de saúde e métricas de desempenho
  • ✅ Adicionado sistema de registro estruturado
  • ✅ Aprimorada validação e saneamento de entrada
  • ✅ Adicionados tempos de espera e configurações de repetição configuráveis
  • ✅ Melhorada análise JSON com múltiplas estratégias de fallback