# 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](https://console.x.ai/) 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`

```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

<details>
<summary>For users behind proxy/VPN</summary>

Add proxy environment variable to your config:

```json
{
  "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.
</details>

## Local Development

<details>
<summary>Build from source</summary>

```bash
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
```
</details>

## 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