# grok-mcp

FastMCP server for searching X (Twitter) via the xAI Grok API.

Uses the xAI [Responses API](https://docs.x.ai/docs/api-reference) with the `x_search` server-side tool — Grok autonomously searches X, analyses results, and returns a grounded answer with citations.

## Tools

### `search_x`

Search X posts and get a summarised answer with source citations.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `query` | `str` | *required* | Natural-language search query |
| `allowed_handles` | `list[str]` | `None` | X usernames to restrict search to (max 10) |
| `excluded_handles` | `list[str]` | `None` | X usernames to exclude (max 10) |
| `from_date` | `str` | `None` | Start date filter (ISO 8601, e.g. `2026-02-01`) |
| `to_date` | `str` | `None` | End date filter (ISO 8601) |
| `enable_image_understanding` | `bool` | `True` | Analyse images in posts |
| `enable_video_understanding` | `bool` | `False` | Analyse video clips in posts |
| `model` | `str` | `grok-4-1-fast` | Grok model to use |
| `system_prompt` | `str` | `None` | Custom system prompt |
| `temperature` | `float` | `None` | Sampling temperature (0-2) |

**Returns:** `{ text, citations?, model, usage }`

## Setup

1. Get an API key from [console.x.ai](https://console.x.ai)

2. Copy the env template and add your key:
   ```bash
   cp .env.example .env
   # edit .env with your XAI_API_KEY
   ```

3. Install dependencies:
   ```bash
   uv sync
   ```

## Usage with Claude Code

Add to your Claude Code MCP config (`~/.claude/settings.json` or project `.claude/settings.json`):

```json
{
  "mcpServers": {
    "grok": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/grok", "python", "server.py"]
    }
  }
}
```

## Model Options

| Model | Context | Input $/1M | Output $/1M | Notes |
|-------|---------|-----------|------------|-------|
| `grok-4-1-fast` | 2M | $0.20 | $0.50 | Default — fast, cheap, great for search |
| `grok-4.1` | 256K | $3.00 | $15.00 | Flagship reasoning |
| `grok-3` | 128K | $2.00 | $10.00 | Stable general purpose |

Live search costs an additional ~$0.025 per source retrieved.