merterbak/Grok-MCP
MCP server for full Grok web access via browser cookies
Installation
npx grok-mcpAsk AI about merterbak/Grok-MCP
Powered by Claude Β· Grounded in docs
I know everything about merterbak/Grok-MCP. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
Grok-MCP
MCP server for xAI's Grok API with agentic tool calling, image and video generation, vision, and file support.
Features
- Agentic Tool Calling: Web search, X search, and code execution with multi-step reasoning
- Multiple Grok Models: Access to latest models such as grok-4.20-0309-reasoning, grok-4-1-fast-reasoning and more
- Image and Video Generation: Create images and videos using Grok Imagine
- Vision Capabilities: Analyze images with Grok's vision models
- Files API: Upload, manage, and chat with documents
- Stateful Conversations: Maintain conversation context as id across multiple requests
- Local Chat History: Option to save persistent client side chat history as JSON files in chats/
Prerequisites
- Python 3.11 or higher
- xAI API key (Get one here)
- Astral UV
Installation
- Clone the repository:
git clone https://github.com/merterbak/Grok-MCP.git
cd Grok-MCP
- Create a venv environment:
uv venv
source .venv/bin/activate # macOS/Linux or .venv\Scripts\activate on Windows
- Install dependencies:
uv sync
Configuration
Claude Desktop Integration
Add this to your Claude Desktop configuration file:
{
"mcpServers": {
"grok": {
"command": "uv",
"args": [
"--directory",
"/path/to/Grok-MCP",
"run",
"python",
"main.py"
],
"env": {
"XAI_API_KEY": "your_api_key_here"
}
}
}
}
Claude Code Integration
Run this command from inside the project directory:
claude mcp add grok-mcp -e XAI_API_KEY=your_api_key_here -- uv run --directory /path/to/Grok-MCP python main.py
Or if you have a .env file with your key:
claude mcp add grok-mcp -- uv run --directory /path/to/Grok-MCP python main.py
Verify it's registered:
claude mcp list
Filesystem MCP (Optional)
Claude Desktop can't send uploaded images in the chat to an MCP tool. The easiest way to give access to files directly from your computer is official Filesystem MCP server. After setting it up youβll be able to just write the imageβs file path (such as /Users/mert/Desktop/image.png) in chat and Claude can use it with any vision chat tool.
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-filesystem",
"/Users/<your-username>/Desktop",
"/Users/<your-username>/Downloads"
]
}
}
}
For stdio:
uv run python main.py
Docker:
docker compose up --build
Mcp Inspector:
mcp dev main.py
Available Tools
Each tool has a full docstring in src/server.py with its arguments and return format. MCP client surfaces those directly, so this list is just a quick map of what's available.
Note: For using images and files, you must provide paths to chat. See Filesystem MCP (Optional) for setup.
Chat and reasoning
chatβ standard chat completion with optional persistent history and multi-agent support.chat_with_visionβ analyze local or remote images with a Grok vision model.chat_with_filesβ chat grounded on previously uploaded documents.stateful_chatβ continue a server-side stored conversation viaresponse_id.retrieve_stateful_responseβ fetch a stored response by ID.delete_stateful_responseβ delete a stored response by ID.
Agentic tools
web_searchβ autonomous web research with domain filters and citations.x_searchβ autonomous search over X (Twitter) posts, with handle and date filters.code_executorβ solve tasks by running Python in a sandbox.grok_agentβ unified agent that mixes files, images, web search, X search, and code execution.
Image and video
generate_imageβ create or edit images with Grok Imagine (multi-reference editing supported).generate_videoβ text-to-video, image-to-video, or video editing with Grok Imagine.extend_videoβ extend an existing generated video with a follow-up prompt.
Files
upload_fileβ upload a local document.list_filesβ list uploaded files with sorting.get_fileβ fetch file metadata by ID.get_file_contentβ download file content as text.delete_fileβ delete a file by ID.
Local chat history
list_chat_sessionsβ list saved sessions inchats/.get_chat_historyβ get a session's full transcript.clear_chat_historyβ delete a session's local history file.
Models
list_modelsβ list all Grok language and image models with live pricing.
License
This project is open source and available under the MIT License.
