grok MCP server
Commit Nov 8, 2026Integrates xAI Grok into MCP clients to enable text, image, and video generation alongside real-time X search.
Also known as libraz/grok-mcp
- Stars
- 4
- Tools
- 6
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 8, 2026
- License
- MIT
What is grok MCP?
grok integrates xAI Grok into MCP clients to enable text, image, and video generation alongside real-time X search. It exposes 6 tools, such as grok_ask, grok_list_models, grok_imagine_image.
Summary generated from the project's README
About grok MCP server
Accessing xAI Grok capabilities from within Claude Code or Codex CLI is what this MCP server enables. It allows developers to integrate advanced text, image, and video generation directly into their existing AI workflows. By connecting to the xAI API, users can perform real-time X search, process image inputs, and generate high-quality visual content using specific tools like grok_imagine_image and grok_imagine_video.
Users can choose between two distinct backends depending on their needs. The API backend requires an XAI_API_KEY and provides the full feature set, including X search and media generation. Alternatively, the CLI backend uses a local grok subprocess via an existing subscription, which avoids per-token billing but is limited to text-only interactions. This flexibility makes it suitable for both developers wanting deep multimodal integration and those looking to utilize their existing Grok subscriptions without extra costs.
What you can do with it
- 1Real-time social media researchAsk the AI to find the latest posts from specific accounts on X using the built-in search functionality.
- 2Visual content creationGenerate new images or edit existing ones by providing up to five source images to the model.
- 3Text-to-video generationCreate cinematic video clips from a text prompt or animate a still image.
- 4Budget managementCalculate the expected USD cost for specific model requests based on token counts or video duration.
Written from the project's README. Every use case is checked against a quote from it.
grok MCP tools 6
Detected from the READMEgrok_askgrok_list_modelsgrok_imagine_imagegrok_imagine_videogrok_imagine_video_statusgrok_estimate_cost
| grok_ask | — | |
| grok_list_models | — | |
| grok_imagine_image | — | |
| grok_imagine_video | — | |
| grok_imagine_video_status | — | |
| grok_estimate_cost | — |
Configuration
XAI_API_KEYXAI_DEFAULT_MODEL
| Name | Description | |
|---|---|---|
| XAI_API_KEY | — | |
| XAI_DEFAULT_MODEL | — |
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablelibraz/grok-mcp is public and reachablegithub.com/libraz/grok-mcp ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-08github.com/libraz/grok-mcp ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model6 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubgrok-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.7, grok-4.6, grok-4.5, … (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.7. 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.7"
}
}
}
}
Codex CLI (~/.codex/config.toml):
[mcp_servers.grok]
command = "npx"
args = ["-y", "github:libraz/grok-mcp"]
env = { XAI_DEFAULT_MODEL = "grok-4.7" }
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.7 |
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.7", // 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, 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; each source image bills at the model's per-input-image rate. When editing, the output aspect ratio follows the first source image unless aspect_ratio is set. grok-imagine-image-quality was retired on 2026-11-02; xAI serves requests to it with grok-imagine-image-2.0 at low quality and bills them at that rate.
grok_imagine_video
{
"prompt": "Cinematic drone shot over a coastal town at sunset",
"model": "grok-imagine-video-1.5", // optional, video / video-1.5 / video-1.5-lite, default grok-imagine-video-1.5
"image": "./still.png", // optional, animates this still instead of text-to-video
"duration": 6, // optional, 1-15, default 8
"aspect_ratio": "16:9", // optional, also 21:9 / 5:2 etc., default 16:9
"resolution": "720p", // optional, 480p / 720p / 1080p, default 480p
"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. grok-imagine-video renders up to 720p, and image-to-video output follows the still's aspect ratio.
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.7", "input_tokens": 12000, "output_tokens": 800, "cached_input_tokens": 9000 }
{ "model": "grok-imagine-image-2.0", "image_count": 4, "source_image_count": 2, "resolution": "2k", "quality": "medium" }
{ "model": "grok-imagine-video-1.5", "video_seconds": 10, "resolution": "720p" }
Uses a static pricing snapshot (2026-10-28). 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. Image and video rates depend on resolution (and quality for grok-imagine-image-2.0), defaulting to what xAI renders when unset; a video without video_seconds is priced at the default 8 seconds. Source images (an edit's inputs or an image-to-video still) bill at a separate per-input-image rate, so pass source_image_count to have them priced in. Verify current rates at docs.x.ai/developers/models.
License
grok MCP questions
What tools does grok MCP provide?
It exposes 6 tools, including grok_ask, grok_list_models, grok_imagine_image, grok_imagine_video, grok_imagine_video_status.
Can I use Grok to search X (Twitter) through this server?
Yes, the 'api' backend supports real-time X search via the 'search' parameter in the grok_ask tool.
Does the CLI backend support image or video generation?
No, the CLI backend is text-only; image and video generation tools will return an error if using the CLI mode.