MCP Directory

How to add Grok-MCP to Windsurf

MCP server for xAI's Grok API: agentic tool calling, image/video generation, vision, and file support. Paste the config into ~/.codeium/windsurf/mcp_config.json and restart Windsurf.

Last updated June 14, 2026 · 39★ · stdio · apikey

Windsurf config for Grok-MCP

git clone https://github.com/merterbak/Grok-MCP.git && cd Grok-MCP && uv venv && uv sync
{
  "mcpServers": {
    "grok-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/Grok-MCP",
        "run",
        "python",
        "main.py"
      ],
      "env": {
        "XAI_API_KEY": "your_api_key_here"
      }
    }
  }
}

Setup steps

  1. 1Open Windsurf → Cascade → the hammer/MCP icon → Configure (or edit ~/.codeium/windsurf/mcp_config.json).
  2. 2Paste the Grok-MCP config below.
  3. 3Fill in placeholder secrets, then save.
  4. 4Click Refresh in the MCP panel.
  5. 5Grok-MCP's tools become available to Cascade.

Before you start

  • Python 3.11 or higher
  • xAI API key (from https://console.x.ai)
  • Astral UV package manager

What Grok-MCP can do in Windsurf

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 via response_id.

retrieve_stateful_response

Fetch a stored response by ID.

delete_stateful_response

Delete a stored response by ID.

web_search

Autonomous web research with domain filters and citations.

x_search

Autonomous search over X (Twitter) posts, with handle and date filters.

Security

Requires an xAI API key (XAI_API_KEY) passed via environment. Claude Desktop cannot send uploaded chat images to MCP tools; the README recommends pairing with the official Filesystem MCP so you can reference local image/file paths in chat. Usage incurs xAI API costs (chat, image/video generation, agentic tools).

Grok-MCP + Windsurf FAQ

Where is the Windsurf config file?

Windsurf reads MCP servers from ~/.codeium/windsurf/mcp_config.json. Paste the Grok-MCP config there under the "mcpServers" key and restart the client.

Is Grok-MCP safe to use with Windsurf?

Requires an xAI API key (XAI_API_KEY) passed via environment. Claude Desktop cannot send uploaded chat images to MCP tools; the README recommends pairing with the official Filesystem MCP so you can reference local image/file paths in chat. Usage incurs xAI API costs (chat, image/video generation, agentic tools).

How do I authenticate?

Set the XAI_API_KEY environment variable in your MCP client config with a key from the xAI console (https://console.x.ai).

Why can't I send an image directly in Claude Desktop chat?

Claude Desktop can't pass uploaded chat images to an MCP tool. The README recommends installing the official Filesystem MCP so you can reference a local file path (e.g. /Users/me/Desktop/image.png) in chat for the vision tools.

How do I install it for Claude Code?

Run from 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

View repo Full Grok-MCP page