Grok MCP Server

A Model Context Protocol (MCP) server that brings xAI's Grok API into Claude Code as native tools.

Ask Grok questions, generate images with Aurora, run multi-round consensus analysis, and explore available models — directly from your terminal.

Tools

Built-in Protocols

Consensus Validation Protocol (CVP)

The grok_consensus tool implements a structured, multi-round analysis protocol. Instead of a single prompt-and-response, it runs 3-10 iterative rounds where Grok progressively deepens its analysis — challenging its own assumptions, evaluating evidence strength, and synthesizing a balanced conclusion.

> Run CVP on whether large language models can reason
> Ask Grok to validate the claim that sleep deprivation affects decision-making — use 5 rounds
> Consensus check with Grok on the future of nuclear energy

The entire protocol executes server-side in a single tool call. Each round builds on the full conversation history for genuine iterative refinement.

Default: 3 rounds | Max: 10 rounds | Full protocol documentation

Validation Protocol

The grok_validate tool runs a rigorous, multi-round quality gate on any artifact — code, plans, research, prompts, PR descriptions, architectures. Grok produces a scored scorecard (correctness, completeness, innovation/risk, clarity, best practices), identifies critical issues, and returns an improved version ready to copy-paste.

> grok_validate with artifact is [paste your plan or code here]
> grok_validate with artifact is [auth module] criteria is security, input validation rubric is security-focused
> grok_validate with artifact is [your plan] reference is [original output] rounds is 6 rubric is strict

Supports four rubric presets: balanced (default), strict, innovative, and security-focused. An optional reference argument enables side-by-side comparison with another model's output.

Default: 5 rounds | Max: 10 rounds

Prerequisites

• Node.js >= 18

• Claude Code CLI installed

• xAI API key — get one at console.x.ai

Setup

Option A: Install from npm

npm install -g askgrokmcp

Then register with Claude Code:

claude mcp add grok -e XAI_API_KEY=your_api_key_here -- grok-mcp

Option B: Clone from source

git clone https://github.com/marceloceccon/askgrokmcp.git
cd askgrokmcp
npm install

Then register with Claude Code:

claude mcp add grok -e XAI_API_KEY=your_api_key_here -- node /path/to/askgrokmcp/grok-mcp.mjs

Replace /path/to/askgrokmcp with the actual path where you cloned the repository.

Replace your_api_key_here with your xAI API key in either option. That's it — the tools are now available in Claude Code.

Usage

Once registered, you can use the tools naturally in Claude Code:

Ask Grok a question

> ask grok what the latest news in AI are

Use a system prompt

> ask grok to review this code, using a system prompt that says "You are a senior security auditor"

Control sampling parameters

> ask grok to generate test data with temperature 0 and max_tokens 500

Use a specific model for one call

> ask grok to summarize this document using grok-3

Generate an image

> ask grok to generate an image of a sunset over mountains and save it as images/sunset.png

Generate multiple variations

> ask grok to generate 4 variations of a logo for a coffee shop and save them as images/logo.png

When generating multiple images, files are automatically numbered (e.g., logo-1.png, logo-2.png, ...).

Run a consensus analysis

> run CVP on the effectiveness of carbon capture technology
> ask grok to validate whether quantum computers will break RSA by 2030 — use 5 rounds

List available models

> list the available grok models
> list grok chat models only
> list grok image models

Model Selection

The server uses a three-level priority system for model selection:

Built-in defaults

At startup the server probes the xAI /models endpoint and selects the best available model:

If the frontier model is not available on your account, the server automatically falls back to the safe default.

Change defaults via environment variable

claude mcp add grok \
  -e XAI_API_KEY=your_api_key_here \
  -e GROK_CHAT_MODEL=grok-3 \
  -e GROK_IMAGE_MODEL=grok-2-image \
  -- grok-mcp

Override per call

Just tell Claude which model to use:

> ask grok to explain quantum computing using model grok-3

Or use list_models first to discover what's available, then pick one.

File write safety

By default the server only writes images inside the current working directory (the directory Claude Code was launched from) and its subdirectories. Any path that resolves outside that directory is rejected with a clear error.

To allow writes to a different location, set the SAFE_WRITE_BASE_DIR environment variable to an absolute path:

export SAFE_WRITE_BASE_DIR=/tmp/my-images

Or pass it directly when registering the server:

claude mcp add grok \
  -e XAI_API_KEY=your_api_key_here \
  -e SAFE_WRITE_BASE_DIR=/tmp/my-images \
  -- grok-mcp

Note: Absolute paths that resolve outside the allowed base directory are rejected. Use relative paths (e.g. images/output.png) or set SAFE_WRITE_BASE_DIR explicitly.

Configuration

Request logging

Request logging is optional and disabled by default.

Enable metadata-only logs:

export LOG_REQUESTS=true

To also log full request payloads (including prompts), explicitly enable:

export LOG_REQUESTS=true
export LOG_REQUEST_PAYLOADS=true

Important: Logs are written to stderr (not stdout) so MCP protocol communication remains safe.

Project Structure

askgrokmcp/
  grok-mcp.mjs          Server entry point, config, HTTP client
  src/tools.js           Tool definitions and handler implementations
  protocols/             Protocol documentation
    consensus-validation.md
  grok-mcp.test.mjs     Test suite

How it works

This server implements the MCP protocol over stdio. When Claude Code starts, it launches the server as a subprocess and communicates with it via JSON-RPC over stdin/stdout. The server translates MCP tool calls into xAI API requests and returns the results.

flowchart LR
    A[Claude Code] -- stdio --> B[grok-mcp.mjs]
    B -- HTTPS --> C[xAI API]

For the grok_consensus tool, the server manages a multi-round conversation loop with Grok internally, returning the complete analysis in a single response:

sequenceDiagram
    participant C as Claude Code
    participant S as grok-mcp
    participant G as xAI API

    C->>S: grok_consensus(topic, rounds)
    loop Each round
        S->>G: chat/completions (with full history)
        G-->>S: Round analysis
    end
    S-->>C: Structured CVP results

License

MIT