Grok2API MCP Server
English · 中文
An MCP (Model Context Protocol) server that provides real-time web search via Grok. Returns structured results with source URLs, confidence scores, key points, and multi-language support.
How It Works
Claude / Cursor / etc. ──MCP──> grok-mcp-server ──HTTP──> grok2api ──> Grok
This server bridges MCP clients to a grok2api-compatible backend, exposing Grok's real-time web search through an OpenAI-compatible API.
Features
- Real-time web & Twitter/X search via Grok
- Structured JSON output — summary, key points with citations, source list, confidence score
- Multiple output modes —
brief,analyst,raw - Multi-language support — respond in any language
- Time range filtering —
24h,7d,30d,all - Source freshness control — prefer recent sources
- Domain allowlist preference — prioritize trusted domains (best-effort)
- Automatic retries with exponential backoff
- Runtime metrics via
grok_statstool
Prerequisites
You need a running grok2api instance (or any OpenAI-compatible API endpoint backed by a Grok model with web search).
Setting Up the grok2api Backend
It is strongly recommended to use a secondary/alt Grok account for this, not your primary account.
1. Deploy grok2api
Choose the method that fits your environment:
Requires Docker and Docker Compose installed on your server.
git clone https://github.com/chenyme/grok2api
cd grok2api
docker compose up -d
The admin panel will be available at http://your-server-ip:8000/admin (default password: grok2api).
Requires Python 3.11+ and uv.
# Install uv if you don't have it
brew install uv
# Clone and run
git clone https://github.com/chenyme/grok2api
cd grok2api
uv sync
uv run main.py
The admin panel will be at http://localhost:8000/admin (default password: grok2api).
Requires Python 3.11+ and uv.
# Install uv (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
# Clone and run
git clone https://github.com/chenyme/grok2api
cd grok2api
uv sync
uv run main.py
The admin panel will be at http://localhost:8000/admin (default password: grok2api).
Requires Python 3.11+ and uv.
# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh
# Clone and run
git clone https://github.com/chenyme/grok2api
cd grok2api
uv sync
uv run main.py
The admin panel will be at http://localhost:8000/admin (default password: grok2api).
For cloud deployments (Vercel, Render), see the grok2api README.
2. Get Your Grok Cookie
- Log into grok.com with your Grok account
- Open browser DevTools (
F12orCmd+Opt+I) - Go to the Application tab
- In the left sidebar, expand Storage → Cookies
- Find the cookie named
ssoorsso-rw - Copy its value
3. Add Token to grok2api
- Open the grok2api admin panel (
http://your-server:8000/admin) - Click Add to add a new token
- Paste the cookie value you just copied
- Select your account type based on your Grok subscription:
- Basic — 80 requests per 20 hours
- Super — 140 requests per 2 hours
The GROK_API_KEY in your .env is the admin key configured in grok2api (the app.app_key value, default: grok2api).
Installation
Option A: Global install (recommended)
git clone https://github.com/wousp112/grok2api-mcp-server.git
cd grok-mcp-server
cp .env.example .env
# Edit .env with your API URL and key
npm install
npm link
Option B: Local install
git clone https://github.com/wousp112/grok2api-mcp-server.git
cd grok-mcp-server
cp .env.example .env
# Edit .env with your API URL and key
npm install
Configuration
Copy .env.example to .env and fill in your values:
MCP Client Configuration
Add to ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"grok-search": {
"command": "grok-mcp-server",
"args": [],
"env": {
"PATH": "/usr/local/bin:/usr/bin:/bin"
}
}
}
}
{
"mcpServers": {
"grok-search": {
"command": "grok-mcp-server",
"args": []
}
}
}
Add to .cursor/mcp.json:
{
"mcpServers": {
"grok-search": {
"command": "grok-mcp-server",
"args": []
}
}
}
Note: If you skipped
npm link, use the full path instead:"command": "/path/to/grok-mcp-server/index.js"
Tools
grok_web_search
Search the web or Twitter/X via Grok with structured output.
Response structure:
{
"summary": "Concise factual summary",
"key_points": [
{ "point": "Key finding", "source_urls": ["https://..."] }
],
"sources": [
{
"title": "Article Title",
"url": "https://...",
"publisher": "Publisher Name",
"published_at": "2025-01-01T00:00:00Z",
"relevance_note": "Why this source matters"
}
],
"confidence": 0.85,
"as_of": "2025-01-01T12:00:00Z",
"notes": "Additional context or caveats"
}
grok_stats
Returns runtime metrics: call counts, error distribution, uptime.
Acknowledgements
- grok2api by chenyme — the backend that makes Grok accessible via OpenAI-compatible API
License
MIT
