Grok MCP

Grok-MCP

Servidor MCP para a API Grok da xAI com busca na Web/X, visão, geração de imagens/vídeos e suporte a arquivos.

Recursos

• Chamada de Ferramentas Agênticas: Busca na Web, busca no X e execução de código com raciocínio em múltiplas etapas
• Múltiplos Modelos Grok: Acesso aos modelos mais recentes, como grok-4.6, grok-4.5, grok-build-0.1 e outros
• Geração de Imagens e Vídeos: Crie imagens e vídeos usando o Grok Imagine
• Capacidades de Visão: Analise imagens com os modelos de visão da Grok
• API de Arquivos: Envie, gerencie e converse com documentos
• Conversas com Estado: Mantenha o contexto da conversa como id em múltiplas solicitações
• Histórico de Chat Local: Opção de salvar o histórico de chat persistente no lado do cliente como arquivos JSON em chats/

Pré-requisitos

• Python 3.11 ou superior
• Chave de API da xAI (Obtenha uma aqui)
• Astral UV

Instalação

1. Clone o repositório:

git clone https://github.com/merterbak/Grok-MCP.git
cd Grok-MCP

2. Crie um ambiente venv:

uv venv
source .venv/bin/activate # macOS/Linux or .venv\Scripts\activate on Windows

3. Instale as dependências:

uv sync

Configuração

Integração com Claude Desktop

Adicione isto ao seu arquivo de configuração do Claude Desktop:

{
  "mcpServers": {
    "grok": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/Grok-MCP",
        "run",
        "python",
        "main.py"
      ],
      "env": {
        "XAI_API_KEY": "your_api_key_here"
      }
    }
  }
}

Integração com Claude Code

Execute este comando dentro do diretório do projeto:

claude mcp add grok-mcp -e XAI_API_KEY=your_api_key_here -- uv run --directory /path/to/Grok-MCP python main.py

Ou, se você tiver um arquivo .env com sua chave:

 claude mcp add grok-mcp -- uv run --directory /path/to/Grok-MCP python main.py

Verifique se está registrado:

claude mcp list

Filesystem MCP (Opcional)

O Claude Desktop não consegue enviar imagens carregadas no chat para uma ferramenta MCP. A maneira mais fácil de dar acesso a arquivos diretamente do seu computador é o servidor oficial Filesystem MCP. Depois de configurá-lo, você poderá apenas escrever o caminho do arquivo da imagem (como /Users/mert/Desktop/image.png) no chat e o Claude poderá usá-lo com qualquer ferramenta de chat com visão.

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/<your-username>/Desktop",
        "/Users/<your-username>/Downloads"
      ]
    }
  }
}

---

Para stdio:

uv run python main.py

Docker:

docker compose up --build

Mcp Inspector:

mcp dev main.py

Ferramentas Disponíveis

Cada ferramenta tem uma docstring completa em src/server.py com seus argumentos e formato de retorno. O cliente MCP expõe isso diretamente, então esta lista é apenas um mapa rápido do que está disponível.

Observação: Para usar imagens e arquivos, você deve fornecer caminhos no chat. Consulte Filesystem MCP (Opcional) para configuração.

Chat e raciocínio

• chat — conclusão de chat padrão com histórico persistente opcional e suporte a múltiplos agentes.
• chat_with_vision — analise imagens locais ou remotas com um modelo de visão da Grok.
• chat_with_files — chat baseado em documentos previamente enviados.
• stateful_chat — continue uma conversa armazenada no servidor via response_id.
• retrieve_stateful_response — recupere uma resposta armazenada por ID.
• delete_stateful_response — exclua uma resposta armazenada por ID.

Ferramentas agênticas

• web_search — pesquisa web autônoma com filtros de domínio e citações.
• x_search — pesquisa autônoma em posts do X (Twitter), com filtros de usuário e data.
• code_executor — resolva tarefas executando Python em um sandbox.
• grok_agent — agente unificado que combina arquivos, imagens, busca web, busca no X e execução de código.

Imagem e vídeo

• generate_image — crie ou edite imagens com o Grok Imagine (suporte a edição com múltiplas referências).
• generate_video — texto para vídeo, imagem para vídeo ou edição de vídeo com o Grok Imagine.
• extend_video — estenda um vídeo gerado existente com um prompt de continuação.

Arquivos

• upload_file — envie um documento local.
• list_files — liste arquivos enviados com ordenação.
• get_file — obtenha metadados de arquivo por ID.
• get_file_content — baixe o conteúdo do arquivo como texto.
• delete_file — exclua um arquivo por ID.

Histórico de chat local

• list_chat_sessions — liste sessões salvas em chats/.
• get_chat_history — obtenha a transcrição completa de uma sessão.
• clear_chat_history — exclua o arquivo de histórico local de uma sessão.

Modelos

• list_models — liste todos os modelos de linguagem e imagem da Grok com preços em tempo real.

Licença

Este projeto é open source e está disponível sob a Licença MIT.