Grok MCP Server

Give Claude Code the power of Grok 4.20

An MCP server that connects Claude Code to xAI's Grok, unlocking real-time web search and X (Twitter) search capabilities.

Why Grok + Claude?

| Grok's Strengths | Use Case | |-------------------|----------| | Web + X Search | Real-time information with transparent source URLs | | X/Twitter Search | Track social media trends, public opinion, breaking news | | 4-Agent Architecture | Harper (research) + Benjamin (logic) + Lucas (creative) collaboration | | 2M Token Context | Massive context window for comprehensive analysis |

Philosophy: Claude is the commander, Grok is the specialist for real-time search and social media intelligence.

Quick Start

1. Get API Key

Visit xAI Console and create an API key.

2. Configure Claude Code

Add to your MCP config file:

• Mac: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "grok-mcp": {
      "command": "npx",
      "args": ["-y", "@lkbaba/grok-mcp@latest"],
      "env": {
        "XAI_API_KEY": "your_xai_api_key_here"
      }
    }
  }
}

@latest ensures you always get the newest version when Claude Code restarts.

3. Restart Claude Code

Tools (2)

grok_agent_search - Smart Search

Real-time web and X (Twitter) search powered by Grok. Grok automatically analyzes queries, executes searches (potentially multiple rounds), synthesizes information, and provides cited answers.

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | query | string | Yes | - | Search query | | search_type | enum | No | mixed | web / x / mixed (recommended) | | model | enum | No | grok-4.20-multi-agent-beta-0309 | See model table below | | output_format | enum | No | text | text (Markdown) / json (native JSON Schema enforced) | | web_search_config | object | No | - | Domain filters (allowed/excluded are mutually exclusive) | | x_search_config | object | No | - | Date range, handle filters (allowed/excluded are mutually exclusive), video understanding |

Output includes: Search results with inline citations, search queries Grok used, titled source links, and usage statistics.

Example:

"Search for the latest Claude Code updates on X and the web"

grok_brainstorm - Creative Brainstorming

Multi-perspective idea generation with project context support.

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | topic | string | Yes | - | Brainstorming topic | | context | string | No | - | Additional context | | context_files | string[] | No | - | Project files to read as context (max 10) | | count | number | No | 5 | Number of ideas (1-10) | | style | enum | No | balanced | innovative / practical / radical / balanced | | model | enum | No | grok-4.20-multi-agent-beta-0309 | Model selection | | output_format | enum | No | text | text (Markdown) / json (native JSON Schema with pros/cons/feasibility) |

Style temperature mapping: practical=0.5, balanced=0.7, innovative=0.95, radical=1.0

Example:

"Brainstorm 3 practical ideas for improving user onboarding, read ./README.md for context"

Model Selection

| Model | Architecture | Price (input/output per M) | Context | Best For | |-------|-------------|---------------------------|---------|----------| | grok-4.20-multi-agent-beta-0309 | 4-Agent collaboration | $2.00 / $6.00 | 2M | Default — lowest hallucination rate (~4.2%) | | grok-4.20-beta-0309-reasoning | Chain-of-thought | $2.00 / $6.00 | 2M | Deep technical analysis | | grok-4.20-beta-0309-non-reasoning | Standard | $2.00 / $6.00 | 2M | Fastest speed, quick creative divergence |

Performance

Tested on 2026-03-12:

| Operation | Model | Time | Tokens | |-----------|-------|------|--------| | Web Search | multi-agent | ~29s | ~70K | | X Search | multi-agent | ~28s | ~48K | | Brainstorm (3 ideas) | multi-agent | ~16s | ~3.6K | | Brainstorm (5 ideas) | non-reasoning | ~7s | ~2.2K |

Proxy Configuration

Add proxy environment variable to your config:

{
  "mcpServers": {
    "grok-mcp": {
      "command": "npx",
      "args": ["-y", "@lkbaba/grok-mcp@latest"],
      "env": {
        "XAI_API_KEY": "your_xai_api_key_here",
        "HTTPS_PROXY": "http://127.0.0.1:7897"
      }
    }
  }
}

Native fetch (undici) automatically reads proxy environment variables.

Local Development

git clone https://github.com/LKbaba/Grok-mcp.git
cd Grok-mcp
npm install
npm run build
export XAI_API_KEY="your_xai_api_key_here"
npm start

Project Structure

src/
├── config/
│   └── index.ts          # Configuration (zod validation)
├── types/
│   └── index.ts          # TypeScript type definitions
├── tools/
│   ├── definitions.ts    # MCP tool JSON Schema definitions
│   ├── agent-search.ts   # grok_agent_search implementation
│   └── brainstorm.ts     # grok_brainstorm implementation
├── utils/
│   ├── grok-client.ts    # xAI API client (native fetch)
│   ├── tool-builder.ts   # Search tool parameter builder
│   └── logger.ts         # Logging and performance monitoring
└── index.ts              # MCP server entry point

Comparison with Gemini MCP

| Feature | Gemini MCP | Grok MCP | |---------|-----------|----------| | Web Search | Google Search (grounding) | Grok Web Search | | X/Twitter Search | Not available | Native support | | Citation URLs | Google redirect (opaque) | Direct URLs with titles (transparent) | | Search Speed | ~8-10s (flash) | ~16-29s (grok-4.20) | | Agent Architecture | Single model | 4-Agent collaboration | | Structured Output | text/json | text/json (native JSON Schema enforced) | | Brainstorm | Structured JSON | Structured JSON + style/count/context_files |

Best strategy: Use both! Gemini for speed and code analysis, Grok for deep search and X/Twitter intelligence.

Security

• Path traversal protection: context_files are sandboxed to the working directory — paths like ../../etc/passwd are blocked
• Sensitive file blocking: .env, .pem, .key, credentials, and database files are automatically excluded
• Input validation: Domain filters, date ranges, handle filters, and file counts are validated with strict schemas
• Mutual exclusivity: allowed_domains/excluded_domains and allowed_x_handles/excluded_x_handles cannot be set simultaneously
• No hardcoded secrets: API keys are loaded from environment variables only

License

MIT