grok-mcp
FastMCP server for searching X (Twitter) via the xAI Grok API.
Uses the xAI Responses API 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
- Get an API key from console.x.ai
- Copy the env template and add your key:
cp .env.example .env
# edit .env with your XAI_API_KEY- Install dependencies:
uv syncUsage with Claude Code
Add to your Claude Code MCP config (~/.claude/settings.json or project .claude/settings.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.
