Grok

You can run and use the Grok MCP Server to connect Grok models and tools with your chat client. It enables agentic tool calling, image and video generation, vision analysis, and document handling in persistent conversations, all accessible through MCP-compatible endpoints.

How to use

You interact with the Grok MCP Server through an MCP client by running the server locally or via an MCP-compatible launcher. You can access multiple Grok models, perform web and X searches, execute code, generate images and videos, analyze images, upload and chat with documents, and maintain context across conversations.

How to install

Prerequisites you must have before starting: Python 3.11 or higher, an xAI API key, and the Astral UV tool.

Step by step installation and startup flow:

# 1) Clone the project
git clone https://github.com/merterbak/Grok-MCP.git
cd Grok-MCP

# 2) Create and activate a virtual environment
uv venv
source .venv/bin/activate  # macOS/Linux
# or: .venv\Scripts\activate  # Windows

# 3) Install dependencies
uv sync

Configuration and usage examples

Configure MCP endpoints to run Grok-MCP locally. The following configurations illustrate how you wire up the server using the UV runner and a local directory. You must provide your own path to the Grok-MCP project and your API key.

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

If you prefer the Claude Code Integration flow, you can start from inside the Grok-MCP project directory using the same startup command, with the API key supplied via environment.

uv run --directory /path/to/Grok-MCP python main.py

Security and access notes

Protect your API key and only expose the MCP endpoint to trusted clients. Use environment configuration to avoid embedding secrets in code or chat prompts.

Troubleshooting tips

If the server does not start, verify your Python version, ensure the virtual environment is activated, and confirm that the API key is valid. Check that the path to the Grok-MCP directory exists and that the main entry point is reachable.

Files integration (optional)

If you plan to work with local files and images, you can set up a Filesystem MCP server to access files directly from your computer. This enables you to reference image paths in chat and use Grok’s vision tools.

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

To start the filesystem MCP server in isolation, run the following command after configuring the paths.

# Start filesystem MCP server (example)
uv run python main.py

Available tools and capabilities

The Grok MCP Server includes a rich set of tools you can use from your client. These tools include model listing, chat with or without vision, image and video generation, web and X searches with agentic behavior, file handling, and stateful conversation management. Use these tools to build complex interactions across multiple requests while preserving context.

Notes on sessions and history

You can maintain persistent conversations across requests by using session identifiers. You can save and load history for chats, upload files, and query stored responses as needed.

Available tools

list_models

List all available Grok models that you can use for conversations and tasks.

chat

Standard chat completion with optional persistent history.

chat_with_vision

Analyze images with text using Grok vision models.

generate_image

Create or edit images from text descriptions or edits.

generate_video

Create or edit videos from text prompts, images, or existing videos.

web_search

Agentic web search with autonomous research across sources.

x_search

Agentic X (Twitter) search for content and updates.

grok_agent

Unified agent combining files, images, and all agentic tools.

code_executor

Execute Python code for calculations and analysis.

stateful_chat

Maintain conversation state across requests.

retrieve_stateful_response

Retrieve a stored conversation.

delete_stateful_response

Delete a stored conversation.

upload_file

Upload a document to chat and search within.

list_files

List uploaded files with sorting options.

get_file

Get file metadata by ID.

get_file_content

Download file content by ID.

delete_file

Delete a file by ID.

chat_with_files

Chat with uploaded documents using agentic document search.

list_chat_sessions

List all saved chat sessions.

get_chat_history

Get full message history for a session.

clear_chat_history

Delete the history for a session.