Grok-MCP

Servidor MCP para la API de Grok de xAI con llamadas a herramientas agénticas, generación de imágenes y vídeo, visión y soporte de archivos.

Características

Llamadas a herramientas agénticas: Búsqueda web, búsqueda en X y ejecución de código con razonamiento de varios pasos
Múltiples modelos Grok: Acceso a los modelos más recientes como grok-4.20-0309-reasoning, grok-4-1-fast-reasoning y más
Generación de imágenes y vídeo: Crea imágenes y vídeos usando Grok Imagine
Capacidades de visión: Analiza imágenes con los modelos de visión de Grok
API de archivos: Sube, gestiona y chatea con documentos
Conversaciones con estado: Mantiene el contexto de la conversación como id a través de múltiples solicitudes
Historial de chat local: Opción para guardar el historial de chat persistente del lado del cliente como archivos JSON en chats/

Related MCP server: Zen MCP Server

Requisitos previos

Python 3.11 o superior
Clave de API de xAI (Obtén una aquí)
Astral UV

Instalación

Clona el repositorio:

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

Crea un entorno venv:

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

Instala las dependencias:

uv sync

Configuración

Integración con Claude Desktop

Añade esto a tu archivo de configuración de Claude Desktop:

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

Integración con Claude Code

Ejecuta este comando desde dentro del directorio del proyecto:

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

O si tienes un archivo .env con tu clave:

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

Verifica que esté registrado:

claude mcp list

Filesystem MCP (Opcional)

Claude Desktop no puede enviar imágenes subidas en el chat a una herramienta MCP. La forma más fácil de dar acceso a archivos directamente desde tu ordenador es el servidor oficial Filesystem MCP. Después de configurarlo, podrás simplemente escribir la ruta del archivo de la imagen (como /Users/mert/Desktop/image.png) en el chat y Claude podrá usarla con cualquier herramienta de chat de visión.

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

Herramientas disponibles

Cada herramienta tiene una cadena de documentación completa en src/server.py con sus argumentos y formato de retorno. El cliente MCP los muestra directamente, por lo que esta lista es solo un mapa rápido de lo que está disponible.

Nota: Para usar imágenes y archivos, debes proporcionar rutas al chat. Consulta Filesystem MCP (Opcional) para la configuración.

Chat y razonamiento

chat — finalización de chat estándar con historial persistente opcional y soporte multi-agente.
chat_with_vision — analiza imágenes locales o remotas con un modelo de visión de Grok.
chat_with_files — chat basado en documentos subidos previamente.
stateful_chat — continúa una conversación almacenada en el servidor mediante response_id.
retrieve_stateful_response — recupera una respuesta almacenada por ID.
delete_stateful_response — elimina una respuesta almacenada por ID.

Herramientas agénticas

web_search — investigación web autónoma con filtros de dominio y citas.
x_search — búsqueda autónoma sobre publicaciones en X (Twitter), con filtros de usuario y fecha.
code_executor — resuelve tareas ejecutando Python en un entorno aislado (sandbox).
grok_agent — agente unificado que combina archivos, imágenes, búsqueda web, búsqueda en X y ejecución de código.

Imagen y vídeo

generate_image — crea o edita imágenes con Grok Imagine (se admite edición con múltiples referencias).
generate_video — texto a vídeo, imagen a vídeo o edición de vídeo con Grok Imagine.
extend_video — extiende un vídeo generado existente con un prompt de seguimiento.

Archivos

upload_file — sube un documento local.
list_files — lista los archivos subidos con ordenación.
get_file — recupera metadatos de archivo por ID.
get_file_content — descarga el contenido del archivo como texto.
delete_file — elimina un archivo por ID.

Historial de chat local

list_chat_sessions — lista las sesiones guardadas en chats/.
get_chat_history — obtiene la transcripción completa de una sesión.
clear_chat_history — elimina el archivo de historial local de una sesión.

Modelos

list_models — lista todos los modelos de lenguaje e imagen de Grok con precios en tiempo real.

Licencia

Este proyecto es de código abierto y está disponible bajo la Licencia MIT.

Grok MCP