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_stats tool

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:

git clone https://github.com/chenyme/grok2api
cd grok2api
docker compose up -d

# 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

# 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

# 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

For cloud deployments (Vercel, Render), see the grok2api README.

2. Get Your Grok Cookie

1. Log into grok.com with your Grok account
2. Open browser DevTools (F12 or Cmd+Opt+I)
3. Go to the Application tab
4. In the left sidebar, expand Storage → Cookies
5. Find the cookie named sso or sso-rw
6. Copy its value

3. Add Token to grok2api

1. Open the grok2api admin panel (http://your-server:8000/admin)
2. Click Add to add a new token
3. Paste the cookie value you just copied
4. 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:

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | GROK_API_URL | Yes | — | Your grok2api endpoint (e.g. http://your-server:8000/v1) | | GROK_API_KEY | Yes | — | API key for authentication | | GROK_MODEL | No | grok-3 | Grok model name | | GROK_REQUEST_TIMEOUT_MS | No | 60000 | Request timeout (ms) | | GROK_MAX_RETRIES | No | 2 | Max retry attempts | | GROK_BACKOFF_BASE_MS | No | 800 | Base backoff delay for retries (ms) | | GROK_READ_TIMEOUT_MS | No | Same as request timeout | Axios timeout (ms) |

MCP Client Configuration

{
  "mcpServers": {
    "grok-search": {
      "command": "grok-mcp-server",
      "args": [],
      "env": {
        "PATH": "/usr/local/bin:/usr/bin:/bin"
      }
    }
  }
}

{
  "mcpServers": {
    "grok-search": {
      "command": "grok-mcp-server",
      "args": []
    }
  }
}

{
  "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.

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | query | string | Yes | — | The question or topic to search for | | output_mode | brief|analyst|raw | No | analyst | Response detail level | | language | string | No | en | Response language code | | time_range | 24h|7d|30d|all | No | all | Search lookback window | | freshness_days | integer | No | — | Prefer sources within N days | | max_sources | integer | No | 8 | Max sources in output (1–20) | | domains_allowlist | string[] | No | — | Preferred source domains, best-effort (max 30) |

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