Skip to main content
Glama

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.

CI License: MIT Python MCP Chrome MV3


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), or max_side to 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 / --sse for 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.json or 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-mcp

One-click install: Install in Cursor Install in VS Code

Agent

How to add it

Claude Code

claude mcp add -s user grok-web -- uvx --from git+https://github.com/h4775346/grok-web-mcp grok-web-mcp

OpenAI Codex CLI

codex mcp add grok-web -- uvx --from git+https://github.com/h4775346/grok-web-mcp grok-web-mcp

Gemini CLI

JSON below in ~/.gemini/settings.json (snippet further down)

VS Code (Copilot)

button above, or code --add-mcp '{"name":"grok-web","command":"uvx","args":["--from","git+https://github.com/h4775346/grok-web-mcp","grok-web-mcp"]}'

Cursor

button above, or the JSON below in ~/.cursor/mcp.json

Claude Desktop

JSON below in claude_desktop_config.json (Settings → Developer → Edit config)

Windsurf

JSON below in ~/.codeium/windsurf/mcp_config.json

Cline

MCP Servers → Configure → JSON below in cline_mcp_settings.json

Roo Code / Kilo Code

JSON below in .roo/mcp.json / .kilocode/mcp.json (or the global MCP settings)

Kiro

JSON below in .kiro/settings/mcp.json

Amazon Q Developer CLI

JSON below in ~/.aws/amazonq/mcp.json

JetBrains AI Assistant / Junie

Settings → Tools → AI Assistant → MCP → Add → paste the JSON below

LM Studio

Program → Install → Edit mcp.json → JSON below

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/sse

Any 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: 600 in Goose or "timeout": 600000 in Cline).

2. Load the Chrome extension

  1. Download grok-web-mcp-extension.zip from the latest release and unzip it, or use the extension/ folder of a clone.

  2. Open chrome://extensions, switch on Developer mode, click Load unpacked and pick the folder.

  3. 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

grok_generate_image

prompt, aspect, n (1–4), mode (speed/quality), size or max_side, out_dir, name. Returns the saved file paths.

grok_batch

A list of image jobs run in order. Refused up front if it does not fit today's budget; jobs over confirm_over submissions need confirm=true.

grok_generate_video

Experimental. prompt, optional image_path to animate, aspect. Returns the mp4 path.

grok_status

Is the extension connected, is a grok tab open, are you logged in.

grok_usage

Today's submissions, images and videos against your limits.

grok_set_limits

Change the daily limits (the agent is told to ask you first).

grok_settings

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 (run grok-web-mcp --init once to create it with every key), or

  • set an environment variable GROK_WEB_MCP_<KEY> (for example GROK_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

output_dir

~/grok-web-mcp

Folder that relative out_dir / image_path values resolve against.

default_aspect

16:9

Aspect ratio when a call does not give one (16:9, 9:16, 1:1, 2:3, 3:2).

default_mode

""

speed or quality when a call does not give one; "" leaves the page as it is.

default_n

1

Images to keep per call when a call does not give n (1–4).

image_timeout_s

180

Seconds to wait for an image submission.

video_timeout_s

420

Seconds to wait for a video.

quota_guard

true

Refuse jobs over the daily limits in limits.json. Usage is still recorded when off.

pin_extension

true

Trust only the first Chrome extension id that connects.

extension_ids

[]

Extension ids always allowed (env: comma-separated).

require_peer_token

true

Require the local peer token (see below).

port

8799

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-mcp

In 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 to extension_ids, or turn pin_extension off.

  • 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

no extension connected

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 grok_status and the popup's port.

Badge says not allowed

Another extension id was pinned first. Edit ~/.grok-web-mcp/extensions.json or set pin_extension to false.

bad token from a second session

Two sessions use different GROK_WEB_MCP_HOME folders. Point them at the same one, or set require_peer_token to false.

invalid setting: ... at start

A value in config.json or a GROK_WEB_MCP_* variable is wrong; grok-web-mcp --config shows which.

not_logged_in

Log in at grok.com in that Chrome profile.

timeout: no images appeared

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

MIT


Available Tools

7 tools
grok_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 limitsB
Idempotent

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 effectA
Read-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 statusA
Read-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 limitsA
Read-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

    A3.9/5.0

    Scored across 7 tools

    Disambiguation5/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers