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

grok-mcp