Grok MCP

grok-mcp

Use Grok as a peer code reviewer and rigorous second-opinion consultant inside Claude Code, Cursor, Cline, OpenClaw, and any other MCP host — talking to xAI's API directly (just an XAI_API_KEY, no install) or via the official Grok CLI.

grok-mcp (npm: grok-cli-mcp) is a Model Context Protocol server for Grok. It gives your primary agent (Claude, Cursor, etc.) four tools so it can delegate to Grok for high-quality second opinions and rigorous validation without leaving the session. As of v0.3.0 it talks to xAI's API directly — no grok binary required — and still supports the CLI for OAuth users:

• grok_review — structured diff review with per-dimension scores
• grok_challenge — thorough analysis for bugs, races, edge cases and security issues
• grok_consult — multi-turn consultation (caller owns history)
• grok_chat — one-shot questions

English | 繁體中文

Why grok-mcp?

Most "Grok MCP" packages expose Grok's chat/search/image capabilities so Claude can *use* Grok. grok-mcp lets your main coding agent (Claude/Cursor/…) ask Grok for a rigorous second opinion on its own work. A different model providing thorough review often catches issues that single-model loops miss.

What you get

Four tools, all stateless, all stdout-only:

Prerequisites

• Node.js ≥ 18
• A backend (the server picks one automatically — see Backends):
• API mode (recommended, zero install): an XAI_API_KEY from console.x.ai. The server calls xAI's HTTP API directly — no extra binary needed.
• CLI mode: the Grok CLI installed, used when no XAI_API_KEY is set: bash curl -fsSL https://x.ai/cli/install.sh | bash Then authenticate with browser OAuth (run grok once interactively). See Authentication below.

Install

npm install -g grok-cli-mcp

or use npx — no install needed

npx grok-cli-mcp

Why the npm name is `grok-cli-mcp` instead of `grok-mcp`? The bare grok-mcp name on npm was already taken by an unrelated project (a Grok HTTP-API integration). The brand, GitHub repo, and MCP server identity stay grok-mcp; only the npm install identifier is grok-cli-mcp — chosen to highlight that this server wraps the official Grok CLI.

Authentication

There are two auth methods, each tied to a backend:

Setting XAI_API_KEY switches the server to API mode, so you can keep your browser login for interactive grok use and use a key *just for this MCP server* via its env block:

{

"mcpServers": { "grok": { "command": "npx", "args": ["-y", "grok-cli-mcp"], "env": { "XAI_API_KEY": "xai-...", "GROK_MCP_TIMEOUT": "600000" } } } }

Treat the key file as a secret — it ends up in your MCP host's config (e.g. ~/.claude.json), which is plain JSON on disk.

Wire it into your MCP host

Claude Code

Recommended — use add-json so the env block parses cleanly:

claude mcp add-json -s user grok '{

"command": "npx", "args": ["-y", "grok-cli-mcp"], "env": { "XAI_API_KEY": "xai-...", "GROK_MCP_TIMEOUT": "600000" } }'

Why `add-json` not `claude mcp add -e ...`? The -e KEY=val flag is variadic and will greedily consume the server name as another env value if you pass more than one. add-json sidesteps that footgun entirely.

Or edit ~/.claude.json directly. Minimal (OAuth fallback):

{

"mcpServers": { "grok": { "command": "npx", "args": ["-y", "grok-cli-mcp"] } } }

Cursor

Create .cursor/mcp.json (project) or ~/.cursor/mcp.json (global):

{

"mcpServers": { "grok": { "command": "npx", "args": ["-y", "grok-cli-mcp"] } } }

Cline (VS Code)

Settings → Cline → MCP Servers:

{

"grok": { "command": "npx", "args": ["-y", "grok-cli-mcp"] } }

Claude Desktop (local, no hosting needed)

Claude Desktop still supports local stdio servers: Settings → Developer → Edit Config (claude_desktop_config.json), then paste the same JSON block as Claude Code above.

Claude Web / Claude Desktop connectors (remote, v0.4+)

Claude's Settings → Connectors → Add custom connector dialog needs an HTTPS URL, not a command — so deploy the bundled Streamable HTTP server and paste its URL:

# 1. Generate a path secret (keeps strangers from spending your xAI credits)

openssl rand -base64 32 | tr '+/' '-_'

2. Deploy anywhere that runs Node (Railway / Fly / Render / a VPS).

A multi-stage Dockerfile ships in the repo:

docker build -t grok-mcp . && docker run \ -e XAI_API_KEY=xai-... \ -e GROK_MCP_PATH_SECRET= \ -p 3000:3000 grok-mcp

...or without Docker:

XAI_API_KEY=xai-... GROK_MCP_PATH_SECRET= npx -y -p grok-cli-mcp grok-mcp-http

Then add the connector in Claude with the URL:

https://your-host.example.com/mcp/<secret-from-step-1>

No OAuth needed — leave the Client ID/Secret fields blank. Claude only starts an OAuth flow if the server asks for it.

Remote-mode notes:

• Treat the URL as a credential. The path secret is what stands between the internet and your xAI bill. Rotate it by changing the env var.
• `grok_review` needs an explicit `diff` over HTTP — the server can't see your local repo, so auto git diff is disabled in remote mode.
• Keep `GROK_MCP_TIMEOUT` below your platform's request timeout (and disable scale-to-zero) — grok-4 reasoning can run for minutes.
• GET /health is available for platform health checks; see .env.example for all knobs (GROK_MCP_ALLOWED_HOSTS, GROK_MCP_CORS_ORIGINS, ...).

Any other MCP host

grok-mcp speaks plain stdio MCP. Point any client at npx -y grok-cli-mcp and it works. HTTP hosts can point at the remote endpoint above instead.

Tool reference

grok_chat

{ "prompt": "Explain consistent hashing in two sentences." }

Optional: model to override the default Grok model; timeout (seconds) to extend the per-call limit for long grok-4 reasoning. All four tools accept timeout.

grok_review

{ "base_ref": "main", "focus": "security" }

If diff is omitted, runs git diff ...HEAD in cwd (defaults to your host's working directory). Returns a markdown review by default with verdict, per-dimension scores (correctness / readability / architecture / security / performance), and concrete fix-it items.

Pass "format": "json" to get machine-parseable output suitable for CI gating — see Use as a PR gate.

grok_consult

{

"messages": [ { "role": "system", "content": "You are a senior backend engineer." }, { "role": "user", "content": "How would you cache this query?" }, { "role": "assistant", "content": "Two options..." }, { "role": "user", "content": "What's the failure mode of option 2?" } ] }

The server is stateless — the caller passes the full thread each time. Most MCP hosts handle this naturally.

grok_challenge

{

"code": "function transfer(from, to, amount) { from.balance -= amount; to.balance += amount; }", "context": "Node.js, called concurrently from HTTP handlers" }

Returns severity-ranked issues (Critical / High / Medium / Low) with concrete reproductions and patches.

Configuration

Backends

The server can reach Grok two ways and chooses one at startup (it logs which to stderr):

• API mode — calls xAI's OpenAI-compatible /chat/completions endpoint directly using Node's built-in fetch. No grok binary required, cleaner errors, pay-per-call. Selected when XAI_API_KEY is set, or forced with GROK_MCP_BACKEND=api.
• CLI mode — shells out to the installed grok binary (supports browser OAuth). Selected when no XAI_API_KEY is set, or forced with GROK_MCP_BACKEND=cli.

Force a mode with GROK_MCP_BACKEND. In API mode, set the model with GROK_MCP_MODEL; in CLI mode, model defaults live in ~/.grok/config.toml.

Timeouts

grok-4 is a reasoning model and long prompts routinely take longer than two minutes. The server's default per-call limit is 300s (5 min). You can change it three ways:

• Per call — pass timeout (seconds) to any tool: { "prompt": "...", "timeout": 600 }.
• Per server — set GROK_MCP_TIMEOUT (milliseconds) in the MCP server's env.
• Host side — the MCP host has its *own* request timeout that can fire before the server's. If calls still time out after raising the above, raise the host limit too. In Claude Code that's MCP_TIMEOUT (server startup) and MCP_TOOL_TIMEOUT (per tool call), both in milliseconds.

On timeout the error includes any partial output Grok produced before the deadline, so you don't lose a near-complete answer.

Use as a PR gate (CI)

grok-mcp ships a grok-review-ci bin and a composite GitHub Action so Grok can review every PR and fail the check on block.

Drop this into .github/workflows/grok-review.yml in your repo:

name: Grok review

on: { pull_request: { branches: [main] } } permissions: { contents: read, pull-requests: write } jobs: grok: runs-on: ubuntu-latest if: ${{ github.event.pull_request.head.repo.full_name == github.repository }} steps:

• uses: actions/checkout@v4 with: { fetch-depth: 0 }
• uses: howardpen9/grok-mcp/.github/actions/grok-review@main with: xai-api-key: ${{ secrets.XAI_API_KEY }} gate-on: block # also accepts: block,request_changes

focus: security # optional

min-score: 6 # optional — fail any dimension below this

The action posts a sticky PR comment with verdict +