Purpose
Grok-MCP is an open-source server based on the MCP protocol, designed to let MCP clients (such as Claude Desktop and Claude Code) call xAI's Grok API through a standardized interface. It wraps Grok's various capabilities into tools that can be invoked by AI agents, making it suitable for developers who want to integrate Grok's reasoning, search, image, and file processing capabilities into existing AI assistant workflows.
Main Capabilities
- Agent tool invocation: Supports web search, X (Twitter) search, code execution, and image generation, and can perform multi-step reasoning.
- Multi-model access: Can call the latest models such as grok-4.6, grok-4.5, and grok-build-0.1.
- Image and video generation: Use Grok Imagine to create or edit images (supports multi-reference editing), generate videos, and extend existing videos.
- Vision capabilities: Analyze local or remote images with Grok vision models.
- File API: Upload, manage, and converse with documents.
- Stateful conversations: Maintain context across multiple requests via response_id.
- Local chat history: Optionally save client chat history as JSON files under chats/.
Usage
Requires Python 3.11 or higher, as well as an xAI API key. Basic steps: clone the repository, create a virtual environment, and install dependencies.
Integrating into Claude Desktop: Add the corresponding configuration to the Claude Desktop configuration file.
Integrating into Claude Code: Run the relevant command within the project directory, or use a .env file containing the key; you can run a verification command to confirm successful registration.
Optional filesystem MCP: Claude Desktop cannot send images uploaded in chat directly to MCP tools. You can use the official Filesystem MCP server, and then write the image file path in chat (such as /Users/mert/Desktop/image.png), and Claude can use it in the vision chat tool.
Examples of available tools (each tool has a complete docstring in src/server.py):
- Chat and reasoning: chat, chat_with_vision, chat_with_files, stateful_chat, retrieve_stateful_response, delete_stateful_response, web_search, x_search, code_executor, grok_agent.
- Images and video: generate_image (save=true can write to images/), generate_video, extend_video.
- File management: upload_file, list_files, get_file, get_file_content, delete_file.
- Local chat history: list_chat_sessions, get_chat_history, clear_chat_history.
- Model list: list_models (lists all Grok language and image models with real-time pricing).
Note: When using images and files, you must provide paths to the chat.
Applicable Scenarios
- Enhance Grok's multimodal reasoning and generation capabilities in Claude Desktop / Claude Code.
- Automated tasks that require web search, X search, or code execution.
- Need to integrate image and video generation and file question answering into AI agent workflows.
- Development and debugging that require maintaining conversation state or saving local chat records.
Limitations
- Requires Python 3.11+ and a valid xAI API key.
- Image and file operations depend on providing local paths, and Claude Desktop requires additional configuration of Filesystem MCP.
- This project is open source under the MIT License; specific pricing is subject to the real-time information returned by list_models. Other details about charges, platforms, or effects are not yet provided.
