Grok Image MCP
_{Image generation & editing for AI coding agents · xAI Grok Imagine · MCP stdio}

Grok Image MCP Server

An MCP (Model Context Protocol) server that brings Grok Imagine image generation and editing to Grok Build, Cursor, Claude Desktop, Claude Code, OpenCode, Hermes Agent, VS Code, Windsurf, and any MCP-compatible client.

Adapted from nano-banana-mcpv2 (Gemini/Imagen) for xAI's image API.

Two Modes — Both Supported

| | Mock mode (free) | Live — subscription OAuth | Live — API key | |---|---|---|---| | Enable | GROK_IMAGE_MOCK=1 | grok login (uses ~/.grok/auth.json) | XAI_API_KEY=... | | API calls | None | xAI Grok Imagine | xAI Grok Imagine | | Cost | Free | Uses SuperGrok / X Premium+ quota | ~$0.02–$0.05 / image | | Use case | Dev, testing, MCP wiring | Subscribers — no API key needed | Pay-as-you-go / teams | | Config examples | examples/ (per-client) | grok-oauth-live.toml | cursor-mcp-live.json |

Switch anytime: unset GROK_IMAGE_MOCK when you're ready for live generation. Subscription users can skip API keys entirely.

# Free — works right now
export GROK_IMAGE_MOCK=1
go build -o grok-image-mcp .
./scripts/test_mock.sh

# Live — SuperGrok / X Premium+ subscribers (no API key)
grok login   # once — stores OAuth in ~/.grok/auth.json
unset GROK_IMAGE_MOCK
./scripts/test_all.sh   # auto-detects OAuth

# Live — pay-as-you-go API key
export XAI_API_KEY="your-key"
unset GROK_IMAGE_MOCK
./scripts/test_all.sh

Sample Output

_{Preview asset · see TEST_REPORT.md for live release proof images per version}

Features

• Generate images — text-to-image via Grok Imagine (grok-imagine-image / grok-imagine-image-quality)
• Edit images — modify existing files with prompts and up to 2 reference images (3 total)
• Continue editing — iteratively refine the last image in a session
• Mock mode — full offline workflow without an API key or credits
• Auto-save — images written to disk automatically for agent follow-up
• Cross-platform — single Go binary, no Node.js runtime

Supported Models

| Model | Speed | Cost | Best for | |---|---|---|---| | grok-imagine-image-quality (default) | Slower | $0.05/image | High-fidelity creative work | | grok-imagine-image | Faster | $0.02/image | Quick drafts and iteration |

Quick Start

1. Build

git clone https://github.com/notfixingit3/grok-image-mcp.git
cd grok-image-mcp
go build -o grok-image-mcp .

2. Configure your MCP client

See Client Integration below for Grok Build, Cursor, Claude, OpenCode, Hermes, VS Code, Windsurf, and Docker.

Clone-and-go: this repo ships with project-level configs — .grok/config.toml (Grok Build), .mcp.json (Claude Code), .cursor/mcp.json (Cursor), and opencode.jsonc (OpenCode, live OAuth via go run .). Open the repo in any of these clients and the tools load automatically (no pre-build needed).

3. Verify

./scripts/test_protocol.sh   # protocol checks (no key)
./scripts/test_mock.sh       # full offline flow (no key)
go test -v ./...             # unit tests

Client Integration

Replace /path/to/grok-image-mcp with your built binary (go build -o grok-image-mcp .) or a release binary. All examples below use mock mode; for live mode, swap GROK_IMAGE_MOCK for XAI_API_KEY.

| Client | Config file | Example | |---|---|---| | Grok Build | ~/.grok/config.toml or .grok/config.toml | grok-build-mock.toml | | Cursor | ~/.cursor/mcp.json or .cursor/mcp.json | cursor-mcp.json | | Claude Desktop | ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) | claude-desktop-mock.json | | Claude Code | .mcp.json in project root (or ~/.claude.json) | claude-code-mock.json | | OpenCode | opencode.jsonc in project root (or ~/.config/opencode/opencode.json) | opencode-oauth-live.jsonc | | Hermes Agent | ~/.hermes/config.yaml under mcp_servers | hermes-oauth-live.yaml | | VS Code (Copilot MCP) | ~/Library/Application Support/Code/User/mcp.json (macOS) | vscode-mcp.json | | Windsurf | ~/.codeium/windsurf/mcp_config.json | windsurf-mcp.json | | Docker | any client's mcpServers block | see Installation Options |

Grok Build also auto-loads .mcp.json, .cursor/mcp.json, and ~/.claude.json for compatibility. Run grok mcp list or grok mcp doctor grok-image-mcp to verify.

Grok Build

Global (~/.grok/config.toml) or project (.grok/config.toml):

[mcp_servers.grok-image-mcp]
command = "/path/to/grok-image-mcp"
env = { GROK_IMAGE_MOCK = "1", GROK_IMAGE_MODEL = "grok-imagine-image-quality" }
enabled = true

Live mode — reference an env var instead of hardcoding the key:

[mcp_servers.grok-image-mcp]
command = "/path/to/grok-image-mcp"
env = { XAI_API_KEY = "${XAI_API_KEY}", GROK_IMAGE_MODEL = "grok-imagine-image-quality" }
enabled = true

CLI:

grok mcp add grok-image-mcp --command /path/to/grok-image-mcp \
  --env GROK_IMAGE_MOCK=1 GROK_IMAGE_MODEL=grok-imagine-image-quality
grok mcp doctor grok-image-mcp

Full examples: grok-build-mock.toml · grok-build-live.toml

Cursor

Edit ~/.cursor/mcp.json (global) or .cursor/mcp.json (project):

{
  "mcpServers": {
    "grok-image-mcp": {
      "command": "/path/to/grok-image-mcp",
      "env": {
        "GROK_IMAGE_MOCK": "1",
        "GROK_IMAGE_MODEL": "grok-imagine-image-quality"
      }
    }
  }
}

Restart Cursor or reload MCP servers from settings. Example: cursor-mcp.json · live: cursor-mcp-live.json

Claude Desktop

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "grok-image-mcp": {
      "command": "/path/to/grok-image-mcp",
      "env": {
        "GROK_IMAGE_MOCK": "1",
        "GROK_IMAGE_MODEL": "grok-imagine-image-quality"
      }
    }
  }
}

Restart Claude Desktop after saving. Examples: claude-desktop-oauth-live.json · mock: claude-desktop-mock.json

Claude Code

Place .mcp.json in your project root (Claude Code walks up to the git root):

{
  "mcpServers": {
    "grok-image-mcp": {
      "command": "/path/to/grok-image-mcp",
      "env": {
        "GROK_IMAGE_MOCK": "1",
        "GROK_IMAGE_MODEL": "grok-imagine-image-quality"
      }
    }
  }
}

This repo includes a ready-to-use .mcp.json (mock mode via go run .). Example: claude-code-mock.json

OpenCode

Add to opencode.jsonc (project root or ~/.config/opencode/opencode.jsonc):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "grok-image-mcp": {
      "type": "local",
      "command": ["/path/to/grok-image-mcp"],
      "environment": {
        "GROK_IMAGE_MOCK": "1",
        "GROK_IMAGE_MODEL": "grok-imagine-image-quality"
      },
      "enabled": true
    }
  }
}

OpenCode uses environment (not env) and command as an array. Verify with opencode mcp list. This repo includes opencode.jsonc (live OAuth, no API key). Examples: opencode-oauth-live.jsonc · opencode-mock.jsonc

Hermes Agent

Add under mcp_servers in ~/.hermes/config.yaml:

mcp_servers:
  grok-image-mcp:
    command: /path/to/grok-image-mcp
    timeout: 120
    enabled: true

SuperGrok / X Premium+ users: run grok login once — no XAI_API_KEY needed. Tools register as mcp_grok-image-mcp_* on startup.

hermes mcp list
hermes mcp test grok-image-mcp
/reload-mcp    # in an active Hermes session

Examples: hermes-oauth-live.yaml · mock: hermes-mock.yaml

VS Code (GitHub Copilot MCP)

Edit ~/Library/Application Support/Code/User/mcp.json (macOS) or the equivalent on your OS:

{
  "mcpServers": {
    "grok-image-mcp": {
      "command": "/path/to/grok-image-mcp",
      "env": {
        "GROK_IMAGE_MOCK": "1",
        "GROK_IMAGE_MODEL": "grok-imagine-image-quality"
      }
    }
  }
}

Example: vscode-mcp.json

Windsurf

Edit ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "grok-image-mcp": {
      "command": "/path/to/grok-image-mcp",
      "env": {
        "GROK_IMAGE_MOCK": "1",
        "GROK_IMAGE_MODEL": "grok-imagine-image-quality"
      }
    }
  }
}

Restart Windsurf / reload MCP. Example: windsurf-mcp.json

Grok Subscription OAuth

If you have SuperGrok or X Premium+, you can use your existing Grok login — no XAI_API_KEY required.

1. Run grok login once (stores credentials in ~/.grok/auth.json)
2. Configure the MCP server normally — no key in env
3. The server auto-detects OAuth and uses your subscription session for image generation

Credential priority (GROK_IMAGE_AUTH, default auto):

1. Grok OAuth (~/.grok/auth.json) — subscription quota
2. XAI_API_KEY environment variable — pay-as-you-go
3. ~/.grok-image-config.json — saved via configure_xai_token

Force API-key-only mode: GROK_IMAGE_AUTH=api_key. Force OAuth-only: GROK_IMAGE_AUTH=oauth.

Check status with the get_configuration_status tool — it reports Grok subscription OAuth is active when OAuth is in use.

Note: Some subscription tiers may return HTTP 403 on OAuth API access. If that happens, fall back to XAI_API_KEY from console.x.ai.

Environment Variables

| Variable | Required | Description | |---|---|---| | XAI_API_KEY | Live (API key mode) | xAI API key from console.x.ai | | GROK_IMAGE_AUTH | No | auto (default), oauth, or api_key | | GROK_AUTH_JSON | No | Path to Grok OAuth store (default: ~/.grok/auth.json) | | GROK_IMAGE_MOCK | No | Set to 1 for free offline mock mode | | GROK_IMAGE_MODEL | No | Default model (grok-imagine-image-quality) | | GROK_IMAGES_DIR | No | Custom output directory for saved images | | GROK_IMAGE_MOCK_ASSET | No | Image file used as mock output | | GROK_IMAGE_LOG_FILE | No | Optional request/response log path |

Config file fallback: ~/.grok-image-config.json via the configure_xai_token tool.

Available Tools

| Tool | Description | |---|---| | generate_image | Create a new image from a text prompt | | edit_image | Edit a specific image file by path | | continue_editing | Edit the last image in the current session | | get_last_image_info | Path, size, and timestamp of the last image | | get_configuration_status | Check API key / mock mode status | | configure_xai_token | Save an xAI API key to ~/.grok-image-config.json |

Installation Options

| Method | Command | |---|---| | Local build | go build -o grok-image-mcp . | | Setup wizard | ./grok-image-mcp --setup (mock or live) | | CLI help | ./grok-image-mcp --help / --version | | Pre-built binary | GitHub Releases | | Docker | docker build -t grok-image-mcp . |

Docker MCP config (live):

{
  "mcpServers": {
    "grok-image-mcp": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "XAI_API_KEY=your-key", "grok-image-mcp"]
    }
  }
}

Docker MCP config (mock — no credits):

{
  "mcpServers": {
    "grok-image-mcp": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "GROK_IMAGE_MOCK=1", "grok-image-mcp"]
    }
  }
}

Troubleshooting

| Issue | What to do | |---|---| | HTTP 403 — no credits/licenses | Add credits at console.x.ai. The server surfaces this with a direct link. | | HTTP 429 — rate limit | Server retries automatically (up to 3 attempts). Wait and retry, or use serviceTier: "default". | | Tools not visible in client | Confirm binary path is absolute, restart/reload MCP, run grok mcp doctor grok-image-mcp (Grok Build). | | No xAI key yet | Use mock mode: GROK_IMAGE_MOCK=1 or ./grok-image-mcp --mock. Subscribers: run grok login instead. | | OAuth 403 after login | Some tiers lack OAuth API access — set XAI_API_KEY or GROK_IMAGE_AUTH=api_key. | | Empty or invalid tool args | v0.2+ validates prompts, enums, and ranges before calling xAI — check the error message. |

Pricing (live mode): grok-imagine-image ~$0.02/image · grok-imagine-image-quality ~$0.05/image. See xAI Imagine docs.

File Storage

| Platform | Default directory | |---|---| | macOS / Linux (dev) | ./generated_imgs/ | | macOS / Linux (system paths) | ~/grok-images/ | | Windows | %USERPROFILE%\Documents\grok-images\ |

Override with GROK_IMAGES_DIR.

Contributing

• dev — active development, pre-releases tagged v*.*.*-beta.*
• main — stable releases (v*.*.*)

Changes go to dev, then PR to main. Tag betas on dev (e.g. v0.2.0-beta.0), stable releases on main.

License & Credits

MIT License — see LICENSE.

• Forked concept from nano-banana-mcpv2
• Image API by xAI Grok Imagine
• Protocol by Anthropic MCP