Grok Web MCP
Generate Grok Imagine images and videos from any MCP-capable AI agent using your own logged-in grok.com Chrome session — no xAI API key.
Generate images (
grok_generate_image): prompt-driven images with aspect ratio (16:9, 9:16, 1:1, 2:3, 3:2), speed/quality mode, 1–4 images per call, exact sizes viasizeormax_side, custom name/output folder, optional original retention.Run batches (
grok_batch): execute up to a dozen image jobs in order, pre-validated and priced against today's quota before anything is submitted; large batches requireconfirm=true.Generate video (
grok_generate_video, experimental): ~6 s clips from a text prompt or by animating a local image.Check health (
grok_status): whether the Chrome extension is connected, a grok.com/imagine tab is open, and the user is logged in.Track usage (
grok_usage): today's image submissions, images kept/generated, and videos versus daily limits.Adjust quota (
grok_set_limits): change daily caps on image submissions, videos, batch size, and the confirmation threshold.Inspect settings (
grok_settings): view effective configuration, each value's source, and what it does.Share one queue across multiple agent sessions, with loopback-only, web-page-blocked, extension-pinned local security.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Grok Web MCP make two 9:16 images of a neon Tokyo street at night, quality mode"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Grok Web MCP
Generate Grok Imagine images and videos from any AI agent (Claude, Codex, Gemini CLI, Cursor, VS Code, Windsurf and more), using the grok.com account you are already logged into. No xAI API key. No per-image billing.
Why
Every other Grok Imagine MCP server calls the paid xAI API. If you already pay for a Grok plan, you are paying twice.
Grok Web MCP drives the Grok Imagine page in your own Chrome, through a small companion extension, and hands the finished files back to your AI assistant. Ask Claude for "a 9:16 cover for my podcast, two options", and two JPGs land in a folder a few seconds later.
Grok Web MCP | API-based Grok MCPs | |
xAI API key | not needed | required |
Cost | your existing Grok plan | billed per image / per video |
Setup | one command + load the extension | API key + billing |
Quota protection | built-in daily limits and batch pre-check | usually none |
Several AI sessions at once | shared queue | separate |
Agents | any MCP agent, stdio or HTTP | varies |
Related MCP server: Grok Image Generation MCP Server
Screenshots
Features
🖼️ Images: aspect ratio (16:9, 9:16, 1:1, 2:3, 3:2), Speed / Quality mode, 1 to 4 images per call.
🎬 Video (experimental): text-to-video or animate a local image.
📦 Batches: run up to a dozen prompts in one call; the whole batch is priced and validated before anything is submitted.
📐 Exact output sizes:
size="1344x768"cover-crops to exact pixels (ready for video models), ormax_sideto shrink.🛡️ Quota guard: a per-day ledger with limits you control, so an over-eager agent cannot burn your daily Grok allowance.
🤖 Every agent: stdio for Claude, Codex, Gemini CLI, Cursor, VS Code, Windsurf, Cline, Zed, Goose…;
--http/--ssefor agents that connect by URL.🔁 Multi-session: open five agent windows; the first becomes the hub and the rest queue through it.
🔒 Local and locked down: loopback only, web pages refused, only your pinned extension id may run jobs.
⚙️ Configurable: default aspect, mode, image count, timeouts and every protection, via
config.jsonor env vars.💾 Never overwrites: files are saved as
name_1.jpg,name_2.jpg,name_1_2.jpg…
Quick start
You need Python 3.10+, uv, Google Chrome (or any Chromium browser) and a grok.com account.
1. Add the MCP server to your AI agent
It works with any agent that supports MCP. Most agents launch it as a local command (stdio):
uvx --from git+https://github.com/h4775346/grok-web-mcp grok-web-mcpOne-click install:
Agent | How to add it |
Claude Code |
|
OpenAI Codex CLI |
|
Gemini CLI | JSON below in |
VS Code (Copilot) | button above, or |
Cursor | button above, or the JSON below in |
Claude Desktop | JSON below in |
Windsurf | JSON below in |
Cline | MCP Servers → Configure → JSON below in |
Roo Code / Kilo Code | JSON below in |
Kiro | JSON below in |
Amazon Q Developer CLI | JSON below in |
JetBrains AI Assistant / Junie | Settings → Tools → AI Assistant → MCP → Add → paste the JSON below |
LM Studio | Program → Install → Edit |
Warp | Settings → AI → MCP servers → Add → paste the JSON below |
Zed, Goose, OpenCode, Continue | see the snippets below |
Anything else | stdio command above, or the HTTP endpoint below |
The JSON most agents use:
{
"mcpServers": {
"grok-web": {
"command": "uvx",
"args": ["--from", "git+https://github.com/h4775346/grok-web-mcp", "grok-web-mcp"]
}
}
}{
"servers": {
"grok-web": {
"type": "stdio",
"command": "uvx",
"args": ["--from", "git+https://github.com/h4775346/grok-web-mcp", "grok-web-mcp"]
}
}
}[mcp_servers.grok-web]
command = "uvx"
args = ["--from", "git+https://github.com/h4775346/grok-web-mcp", "grok-web-mcp"]{
"mcpServers": {
"grok-web": {
"command": "uvx",
"args": ["--from", "git+https://github.com/h4775346/grok-web-mcp", "grok-web-mcp"]
}
}
}{
"context_servers": {
"grok-web": {
"source": "custom",
"command": "uvx",
"args": ["--from", "git+https://github.com/h4775346/grok-web-mcp", "grok-web-mcp"]
}
}
}extensions:
grok-web:
type: stdio
name: grok-web
cmd: uvx
args: ["--from", "git+https://github.com/h4775346/grok-web-mcp", "grok-web-mcp"]
enabled: true
timeout: 600{
"mcp": {
"grok-web": {
"type": "local",
"command": ["uvx", "--from", "git+https://github.com/h4775346/grok-web-mcp", "grok-web-mcp"],
"enabled": true
}
}
}name: grok-web
version: 0.0.1
schema: v1
mcpServers:
- name: grok-web
command: uvx
args: ["--from", "git+https://github.com/h4775346/grok-web-mcp", "grok-web-mcp"]Start the server yourself and point the agent at the URL:
uvx --from git+https://github.com/h4775346/grok-web-mcp grok-web-mcp --http 8000 # http://127.0.0.1:8000/mcp
uvx --from git+https://github.com/h4775346/grok-web-mcp grok-web-mcp --sse 8000 # http://127.0.0.1:8000/sseAny number of agents can connect at once; they share one queue and one daily budget. The HTTP server listens on 127.0.0.1 only.
Tip: video jobs can take several minutes. If your agent has an MCP tool timeout setting, give it 10 minutes (for example
timeout: 600in Goose or"timeout": 600000in Cline).
2. Load the Chrome extension
Download
grok-web-mcp-extension.zipfrom the latest release and unzip it, or use theextension/folder of a clone.Open
chrome://extensions, switch on Developer mode, click Load unpacked and pick the folder.Pin the extension. Its badge turns green on as soon as your MCP client is running.
3. Log in to grok.com
Use the same Chrome profile. That's it. Ask your assistant:
Make two 9:16 images of a neon-lit Cairo rooftop at night with Grok, quality mode, and save them in
rooftop/.
Tools
Tool | What it does |
|
|
| A list of image jobs run in order. Refused up front if it does not fit today's budget; jobs over |
| Experimental. |
| Is the extension connected, is a grok tab open, are you logged in. |
| Today's submissions, images and videos against your limits. |
| Change the daily limits (the agent is told to ask you first). |
| The settings in effect, where each one came from, and what each does. |
grok_generate_image(
prompt="Cinematic night rooftop in Cairo, warm neon, 35mm",
aspect="16:9",
n=2,
mode="quality",
out_dir="rooftop",
size="1344x768",
)
grok_batch(
out_dir="covers",
jobs=[
{"prompt": "minimal album cover, orange sun over the Nile", "name": "cover_a", "aspect": "1:1", "n": 2},
{"prompt": "retro 80s synthwave album cover", "name": "cover_b", "aspect": "1:1"},
],
)
grok_generate_video(
prompt="slow push-in, hair moving in the wind", image_path="rooftop/grok_1.jpg", aspect="16:9", out_dir="clips"
)Quota guard
Every Grok submission counts against your plan's Imagine allowance (one image submission returns 2 images; a
video costs much more). The server keeps a ledger in ~/.grok-web-mcp/usage.json and refuses work beyond
~/.grok-web-mcp/limits.json:
{"max_image_submissions_per_day": 30, "max_videos_per_day": 5, "max_jobs_per_batch": 12, "confirm_over": 10}A refusal tells the agent exactly where it stands, for example
Grok budget: this needs 2 image submission(s) but 29/30 are already used today, so nothing was submitted.
A job that fails after it was submitted (moderation, timeout) still counts, because Grok still charged it.
Settings
Everything works out of the box; nothing below needs to be set. To change a default, either:
edit
~/.grok-web-mcp/config.json(rungrok-web-mcp --initonce to create it with every key), orset an environment variable
GROK_WEB_MCP_<KEY>(for exampleGROK_WEB_MCP_DEFAULT_ASPECT=9:16), which wins over the file.
Check what is in effect with grok-web-mcp --config or the grok_settings tool. Settings are read when the server
starts, so restart your MCP client after a change.
Key | Default | What it does |
|
| Folder that relative |
|
| Aspect ratio when a call does not give one ( |
|
|
|
|
| Images to keep per call when a call does not give |
|
| Seconds to wait for an image submission. |
|
| Seconds to wait for a video. |
|
| Refuse jobs over the daily limits in |
|
| Trust only the first Chrome extension id that connects. |
|
| Extension ids always allowed (env: comma-separated). |
|
| Require the local peer token (see below). |
|
| Local WebSocket port; set the same port in the extension popup. |
GROK_WEB_MCP_HOME (default ~/.grok-web-mcp) moves the whole settings folder. Example for Claude Code:
claude mcp add -s user grok-web -e GROK_WEB_MCP_DEFAULT_ASPECT=9:16 -e GROK_WEB_MCP_DEFAULT_MODE=quality \
-- uvx --from git+https://github.com/h4775346/grok-web-mcp grok-web-mcpIn JSON configs, put the same variables in an "env": { ... } block.
Do I need to do anything with a token?
No. You never copy, paste or type a token, and the Chrome extension does not use one.
Here is why it exists. Each MCP client window starts its own copy of the server. Only the first copy can listen on
the port and talk to Chrome; the others send their jobs to it over the local socket, so all your windows share one
queue and one daily budget. Something has to prove that such a connection really comes from another copy of
grok-web-mcp and not from some other program on your computer trying to spend your Grok quota. That proof is a random
token that the first copy writes to ~/.grok-web-mcp/token.txt and every copy reads by itself.
It is optional. If you only ever run one MCP client, or you trust every program on your computer, set
require_peer_token to false and no token file is created or checked. Web pages stay blocked and the extension pin
still applies either way.
Security
The WebSocket listens on 127.0.0.1 only (not configurable).
Connections from web pages are always refused (any
http(s)://Origin), so a site you visit cannot drive your Grok account.Only a real
chrome-extension://origin can act as the extension, and by default only the first extension id that connects (pinned in~/.grok-web-mcp/extensions.json). Reinstalled from a different folder? Edit that file, add the id toextension_ids, or turnpin_extensionoff.A second MCP session proves itself with the local peer token (automatic; optional, see above).
The extension only has access to
https://grok.com/*. It does not read or send your password or cookies anywhere; it works inside the page you are already logged into, and results go only to the local server.
See SECURITY.md to report a vulnerability.
Troubleshooting
Message | Fix |
| Chrome is closed, or the extension is not loaded. Open Chrome; the badge should say on. |
Badge says off | Your MCP client is not running the server, or the ports differ. Check |
Badge says not allowed | Another extension id was pinned first. Edit |
| Two sessions use different |
| A value in |
| Log in at grok.com in that Chrome profile. |
| The prompt was moderated, you hit Grok's rate limit, or Grok changed its page. |
Jobs are slow when the tab is hidden | Keep Bring the grok tab to front on in the popup (Chrome throttles hidden tabs). |
Grok's web UI changes from time to time. The selectors live in extension/content/main.js;
if something breaks, please open an issue or send a PR.
Development
git clone https://github.com/h4775346/grok-web-mcp && cd grok-web-mcp
uv sync --extra dev
uv run pytest # end-to-end test with a fake extension: no Chrome, no grok.com, no quota used
uv run ruff check .See CONTRIBUTING.md.
Disclaimer
This is an independent open-source project. It is not affiliated with, endorsed by or sponsored by xAI. "Grok" and "Grok Imagine" are trademarks of their owners. The extension automates the grok.com page in your own browser session on your behalf; you are responsible for using it within grok.com's terms of service and your plan's limits.
License
Available Tools
7 toolsgrok_batchGenerate a batch of imagesA
Run several image jobs one after another. Each job: {"prompt", "name", "aspect"?, "n"? (1..4, default 1),
"mode"?, "max_side"?, "size"?, "keep_original"?, "timeout_s"?, "out_dir"?}.
The whole batch is checked first (job count, total submissions vs today's budget); nothing runs if it does not fit.
Batches needing more than confirm_over submissions need confirm=true (ask the user first).
Returns {"results": [...], "submissions_planned", "usage"}; a failed job gets an "error" and the batch goes on,
except budget/no-extension errors, which stop it and mark the rest "skipped".
Inputs: jobs (required), confirm, out_dir.
grok_generate_imageGenerate images with Grok ImagineA
Generate images with Grok Imagine in the user's logged-in Chrome (no API key; uses the user's own Grok plan and daily quota: see grok_usage(); jobs over the limits are refused).
Omitted aspect / n / mode / timeout_s use the configured defaults (see grok_settings). aspect: 16:9 | 9:16 | 1:1 | 2:3 | 3:2. n: images to keep, 1..4 (one submission gives 2; n=3/4 = 2 submissions). mode: "speed" | "quality" (a warning, not a failure, if the page control is not found). max_side: shrink saved files so the long side <= max_side (e.g. 1344). size: exact "WxH" (e.g. "1344x768"), scale to cover + center crop (overrides max_side). keep_original: also keep _orig.. out_dir: absolute, or relative to the output root (GROK_WEB_MCP_OUTPUT_DIR, default ~/grok-web-mcp). Files are _1.jpg, _2.jpg ... (never overwritten). Returns {"files", "kept", "generated", "submissions", "aspect_ok", "secs", "sizes"?, "warning"?}.
Inputs: prompt (required), n, mode, name, +6 more.
grok_generate_videoGenerate a video with Grok Imagine (experimental)A
EXPERIMENTAL: make a Grok Imagine video (about 6 s) from a prompt, optionally animating a local image (image_path: jpg/png/webp). Videos cost much more quota than images and are capped by max_videos_per_day (see grok_usage). Relies on Grok's current web UI, which changes often. Returns {"files": [mp4 path]}.
Inputs: prompt (required), name, aspect, out_dir, +2 more.
grok_set_limitsChange daily limitsBIdempotent
Change the daily Grok quota guard (only when the user asked for it). Omitted values stay as they are.
Inputs: confirm_over, max_jobs_per_batch, max_videos_per_day, max_image_submissions_per_day.
grok_settingsSettings in effectARead-onlyIdempotent
The settings in effect (defaults < config.json < GROK_WEB_MCP_* env vars), where each came from, and what each one does. Settings are read when the server starts; restart the MCP client after changing them.
Inputs: no named parameters.
grok_statusBridge statusARead-onlyIdempotent
Bridge health: is the Chrome extension connected, is a grok.com/imagine tab open, is the user logged in.
Inputs: no named parameters.
grok_usageToday's usage and limitsARead-onlyIdempotent
Today's Grok Imagine usage (image submissions, images generated/kept, videos) against the daily limits.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
Each tool targets a clearly distinct purpose: health/status, settings, usage, quota limits, single image generation, batch generation, and video generation. The only potential overlap is between grok_generate_image and grok_batch, but the batch tool is explicitly scoped to multiple jobs and the single tool remains the obvious choice for one job.
All tools use the same grok_ prefix and snake_case, which makes the set predictable and easy to scan. The pattern is mostly consistent, though some names are noun-style status/settings/usage tools while others are verb_noun operations, so it falls slightly short of a pure verb_noun convention.
Seven tools is well-scoped for this server. Each tool covers a distinct part of the workflow: checking health, reading configuration, monitoring usage, changing limits, and generating images, batches, or videos.
The surface covers the core lifecycle well: status, settings, usage, quota limits, single image generation, batch generation, and experimental video generation. Minor gaps exist around canceling in-flight jobs or listing generated output history, but these are workaroundable and not central to the stated purpose.
Maintenance
Related MCP Connectors
Generate AI images, videos, music, SFX & speech in any AI assistant. Results appear inline in chat.
Generate AI images, video, voiceovers and music from Claude, ChatGPT or Cursor through 50+ models (Veo 3.1, Kling 3, Seedance, Nano Banana, GPT Image, ElevenLabs). Also image editing, upscaling, background removal, face swap, transcription, voice cloning and UGC-style video ads. Sign in with OAuth — no API key to paste. Tools are annotated (read-only vs. credit-spending); failed generations are refunded.
Generate images and video from Claude with one API key.
Generate images from Claude, ChatGPT, Cursor and Codex with 12 top AI image models. Up to 4 images per call, SVG vectorization, background removal, upscaling and image-to-video. Remote MCP with OAuth, no API keys.
Related MCP Servers
- AlicenseAqualityDmaintenanceIntegrates xAI's Grok APIs into Claude Code to enable image and video generation, real-time web searches, and multi-modal image analysis. It provides a suite of tools for interacting with Grok models directly through natural language prompts during a Claude session.541 npm1MIT
- FlicenseNot gradedqualityFmaintenanceEnables AI assistants to generate images via Grok Imagine by automating the web interface through a Chrome extension bridge.1-
- AlicenseNot gradedqualityCmaintenanceEnables image generation and editing via the Grok Imagine Image 2.0 API, supporting text-to-image, image-to-image editing, multi-reference generation, local uploads, and asynchronous job polling.7MIT
- AlicenseAqualityDmaintenanceEnables Claude to generate and edit images using OpenAI's GPT Image models, with automatic model selection and local file saving.31MIT