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 5 source images)
grok_imagine_video	Video generation, text-to-video or from a still (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.6, grok-4.5, grok-4.3, … (grok_list_models)	whatever the signed-in plan offers (grok models)
Text (grok_ask)	✅	✅
Image input (grok_ask images)	✅	❌
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_*, image input 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.6. 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)

Re-running init replaces only the grok entry; other server definitions are kept.

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 into the selected configs. No model is pinned unless GROK_CLI_MODEL is already set in the environment, so the grok CLI's own default model applies. 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.6"
      }
    }
  }
}

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

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

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

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.6	Default model (api)
XAI_TIMEOUT_MS	120000	Request / video polling / CLI timeout
XAI_MAX_IMAGE_MB	20	Max size of a local image file read by any tool — grok_ask images, grok_imagine_image source images, the grok_imagine_video still
GROK_BIN	grok	Path to the grok CLI binary (cli)
GROK_CLI_MODEL	— (the CLI's own default)	Default model passed to the grok CLI (cli)

Tool reference

grok_ask

{
  "prompt": "What are the latest posts from @xai about Grok 4.6?",
  "images": ["https://example.com/diagram.png"],   // optional
  "model": "grok-4.6",                              // 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, up to XAI_MAX_IMAGE_MB). 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-2.0",   // optional, image / image-2.0 / image-quality, default grok-imagine-image-2.0
  "n": 1,                               // optional, 1-10, default 1
  "aspect_ratio": "16:9",               // optional, default "auto" — the model picks
  "resolution": "2k",                   // optional, 1k / 2k, default 1k
  "quality": "medium",                  // optional, low / medium / auto, grok-imagine-image-2.0 only
  "source_images": []                   // only when editing (max 5)
}

Returns xAI-hosted signed URLs — download them if you need to keep them. Source images may be local file paths, http(s) URLs, or data URIs (jpg/jpeg, png, webp) and are referred to in the prompt as <IMAGE_0>, <IMAGE_1>, … in the order passed; editing bills for the source images as well as the generated ones. When editing, the output aspect ratio follows the first source image unless aspect_ratio is set.

grok_imagine_video

{
  "prompt": "Cinematic drone shot over a coastal town at sunset",
  "model": "grok-imagine-video-1.5",   // optional, video / video-1.5, default grok-imagine-video-1.5
  "image": "./still.png",              // optional, animates this still instead of text-to-video
  "duration": 6,                       // optional, 1-15
  "aspect_ratio": "16:9",              // optional
  "resolution": "720p",                // optional, 480p / 720p / 1080p
  "wait": true   // false to return only the request_id
}

duration, aspect_ratio and resolution are omitted from the request when unset, so xAI's own defaults apply.

Polls every 5 seconds within XAI_TIMEOUT_MS. On timeout returns pending — continue with grok_imagine_video_status. A failed or expired job is returned as a tool error, with the reason xAI reported. image takes a local file path, an http(s) URL, or a data URI (jpg/jpeg, png, webp); video input is not supported.

grok_estimate_cost

{ "model": "grok-4.6", "input_tokens": 12000, "output_tokens": 800, "cached_input_tokens": 9000 }
{ "model": "grok-imagine-image-2.0", "image_count": 4, "source_image_count": 2 }
{ "model": "grok-imagine-video-1.5", "video_seconds": 10 }

Uses a static pricing snapshot (2026-09-10). cached_input_tokens is the cheaper cached portion of input_tokens, so xAI's reported usage figures can be passed straight through. A prompt of 200,000 tokens or more moves the whole request to the model's long-context rates, which the estimate applies and reports as tier: long-context. Edits bill for the source images too, so pass source_image_count to have them priced in. Verify current rates at docs.x.ai/developers/models.

License

MIT