grok-mcp

MCP server for the xAI Grok API. Works with Claude Code, Codex CLI, and any other MCP-capable client.

Motivation

Claude Code and Codex CLI already speak MCP, so wrapping Grok as an MCP server lets you call it as a tool from inside the client you already use. Point it at the xAI API (full feature set, including the x_search realtime X / Twitter search that is API-only) or, if you already pay for Grok through the grok CLI, at that CLI instead — no per-token API billing. See Backends.

Tools

Tool	Purpose
grok_ask	Text + image query. search enables X / web search server-side
grok_list_models	List available model IDs
grok_imagine_image	Image generation / editing (up to 3 source images)
grok_imagine_video	Video generation (async; polls until done by default)
grok_imagine_video_status	Poll an in-flight video generation by request_id
grok_estimate_cost	Estimate USD cost from model + tokens / images / video seconds

Backends

XAI_BACKEND selects where responses come from:

	api (default)	cli
Auth	XAI_API_KEY	grok login (OAuth / subscription) — no key needed
Transport	xAI REST API	local grok CLI subprocess
Models	grok-4.3, … (grok_list_models)	grok-build, grok-composer-2.5-fast, …
Text (grok_ask)	✅	✅
Web search	✅	✅ (search: "web" / "both" / true)
X (Twitter) search	✅	❌
Image / video generation	✅	❌

Use cli mode if you already have a Grok subscription via the grok CLI and would rather not pay per API token. It is text-only: grok_imagine_* and X search return a clear error pointing back to api mode. The CLI runs each grok_ask as a single-turn prompt in a temp directory (no project files, web search off unless requested) to keep it a side-effect-free question/answer call.

Quick start

API backend (default)

You need an xAI API key — get one at console.x.ai. Then run:

export XAI_API_KEY="xai-..."
npx -y github:libraz/grok-mcp init

The interactive setup writes the MCP server entry into your selected client configs. By default it does not store XAI_API_KEY in those files; keep the key in the environment used to launch your MCP client. If you explicitly opt into storing the key during init, the generated config file is restricted to user-only permissions where the filesystem supports it.

The default model comes from XAI_DEFAULT_MODEL or falls back to grok-4.3. Pick one or more config targets (comma-separated, e.g. 1,3):

• Claude Code — user (~/.claude.json): active across every Claude Code session
• Claude Code — project (./.mcp.json): active only when Claude Code is opened in the current directory
• Codex CLI (~/.codex/config.toml)

Restart your MCP client to pick up the new server.

CLI backend

Install the grok CLI and sign in, then run init and choose backend 2) grok CLI:

grok login          # one-time OAuth / subscription sign-in
npx -y github:libraz/grok-mcp init

No API key is requested or stored — init writes XAI_BACKEND=cli (and GROK_CLI_MODEL, default grok-build) into the selected configs. Override the binary location with GROK_BIN if grok is not on the launch environment's PATH.

To remove the entry later, run npx -y github:libraz/grok-mcp uninstall — it drops only the grok server, other entries are kept.

Manual setup

If you prefer to edit configs by hand:

Claude Code (~/.claude.json or .mcp.json):

{
  "mcpServers": {
    "grok": {
      "command": "npx",
      "args": ["-y", "github:libraz/grok-mcp"],
      "env": {
        "XAI_DEFAULT_MODEL": "grok-4.3"
      }
    }
  }
}

Codex CLI (~/.codex/config.toml):

[mcp_servers.grok]
command = "npx"
args = ["-y", "github:libraz/grok-mcp"]
env = { XAI_DEFAULT_MODEL = "grok-4.3" }

Only add XAI_API_KEY = "xai-..." to these files if you accept storing a plaintext secret in the MCP client config.

Once published to npm you can drop the github: prefix.

Configuration

Variable	Default	Purpose
XAI_BACKEND	api	Response backend: api or cli
XAI_API_KEY	— (required for api)	xAI API key (not used by cli)
XAI_BASE_URL	https://api.x.ai/v1	Region override / proxy (api)
XAI_DEFAULT_MODEL	grok-4.3	Default model (api)
XAI_TIMEOUT_MS	120000	Request / video polling / CLI timeout
XAI_MAX_IMAGE_MB	20	Max image size accepted as base64 input
GROK_BIN	grok	Path to the grok CLI binary (cli)
GROK_CLI_MODEL	—	Default model passed to the grok CLI (cli)

Tool reference

grok_ask

{
  "prompt": "What are the latest posts from @xai about Grok 4.3?",
  "images": ["https://example.com/diagram.png"],   // optional
  "model": "grok-4.3",                              // optional
  "system": "You are a concise assistant.",         // optional
  "max_tokens": 1024,                               // optional
  "temperature": 0.7,                               // optional, 0-2
  "search": "x"                                     // "x" | "web" | "both" | true | false
}

Images may be local file paths, http(s) URLs, or data URIs. Local files are base64-encoded automatically (jpg/jpeg/png, ≤ 20 MiB). If a remote URL returns xAI API error: 400 Fetching image failed..., switch to a local file path — xAI's fetcher rejects some hosts. search toggles the server-side x_search / web_search tools via the Responses API.

grok_imagine_image

{
  "prompt": "A collage of London landmarks in a stenciled street-art style",
  "model": "grok-imagine-image-quality",   // image / image-quality / image-pro
  "n": 1,
  "aspect_ratio": "16:9",
  "source_images": []                       // only when editing (max 3)
}

Returns xAI-hosted signed URLs — download them if you need to keep them.

grok_imagine_video

{
  "prompt": "Cinematic drone shot over a coastal town at sunset",
  "model": "grok-imagine-video",   // optional, default grok-imagine-video
  "duration": 6,
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "wait": true   // false to return only the request_id
}

Polls every 5 seconds within XAI_TIMEOUT_MS. On timeout returns pending — continue with grok_imagine_video_status. Video input is not supported.

grok_estimate_cost

{ "model": "grok-4.3", "input_tokens": 12000, "output_tokens": 800 }
{ "model": "grok-imagine-image-quality", "image_count": 4 }
{ "model": "grok-imagine-video", "video_seconds": 10 }

Uses a static pricing snapshot (2026-05-13). Verify current rates at docs.x.ai/developers/models.

License

MIT