Grok MCP

Grok-MCP

Servidor MCP para la API de Grok de xAI con búsqueda Web/X, visión, generación de imágenes/videos y soporte de archivos.

Características

• Llamada de herramientas agéntica: Búsqueda web, búsqueda en X y ejecución de código con razonamiento de múltiples pasos
• Múltiples modelos Grok: Acceso a los modelos más recientes como grok-4.6, grok-4.5, grok-build-0.1 y más
• Generación de imágenes y videos: Crea imágenes y videos 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: Mantén el contexto de conversación como id a través de múltiples solicitudes
• Historial de chat local: Opción para guardar historial de chat persistente en el lado del cliente como archivos JSON en chats/

Requisitos previos

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

Instalación

1. Clona el repositorio:

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

2. Crea un entorno venv:

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

3. 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 computadora 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 con 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 docstring completa en src/server.py con sus argumentos y formato de retorno. El cliente MCP las muestra directamente, así que esta lista es solo un mapa rápido de lo que está disponible.

Nota: Para usar imágenes y archivos, debes proporcionar rutas en el 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 previamente subidos.
• 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 en publicaciones de X (Twitter), con filtros de usuario y fecha.
• code_executor — resuelve tareas ejecutando Python en un 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 video

• generate_image — crea o edita imágenes con Grok Imagine (soporta edición multi-referencia).
• generate_video — texto a video, imagen a video o edición de video con Grok Imagine.
• extend_video — extiende un video generado existente con un prompt de seguimiento.

Archivos

• upload_file — sube un documento local.
• list_files — lista archivos subidos con ordenamiento.
• get_file — obtiene 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 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 vivo.

Licencia

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