Grok Image Mcp

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/](examples/) (per-client) | [grok-oauth-live.toml](examples/grok-oauth-live.toml) | [cursor-mcp-live.json](examples/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](#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/config.toml) (Grok Build), [.mcp.json](.mcp.json) (Claude Code), [.cursor/mcp.json](.cursor/mcp.json) (Cursor), and [opencode.jsonc](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](examples/grok-build-mock.toml) | | Cursor | ~/.cursor/mcp.json or .cursor/mcp.json | [cursor-mcp.json](examples/cursor-mcp.json) | | Claude Desktop | ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) | [claude-desktop-mock.json](examples/claude-desktop-mock.json) | | Claude Code | .mcp.json in project root (or ~/.claude.json) | [claude-code-mock.json](examples/claude-code-mock.json) | | OpenCode | opencode.jsonc in project root (or ~/.config/opencode/opencode.json) | [opencode-oauth-live.jsonc](examples/opencode-oauth-live.jsonc) | | Hermes Agent | ~/.hermes/config.yaml under mcp_servers | [hermes-oauth-live.yaml](examples/hermes-oauth-live.yaml) | | VS Code (Copilot MCP) | ~/Library/Application Support/Code/User/mcp.json (macOS) | [vscode-mcp.json](examples/vscode-mcp.json) | | Windsurf | ~/.codeium/windsurf/mcp_config.json | [windsurf-mcp.json](examples/windsurf-mcp.json) | | Docker | any client's mcpServers block | see [Installation Options](#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](examples/grok-build-mock.toml) · [grok-build-live.toml](examples/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](examples/cursor-mcp.json) · live: [cursor-mcp-live.json](examples/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](examples/claude-desktop-oauth-live.json) · mock: [claude-desktop-mock.json](examples/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](.mcp.json) (mock mode via go run .). Example: [claude-code-mock.json](examples/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](opencode.jsonc) (live OAuth, no API key). Examples: [opencode-oauth-live.jsonc](examples/opencode-oauth-live.jsonc) · [opencode-mock.jsonc](examples/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](examples/hermes-oauth-live.yaml) · mock: [hermes-mock.yaml](examples/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](examples/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](examples/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 |

Tool parameters

generate_image

• prompt (required), model, aspectRatio, resolution (1k/2k), numberOfImages (1–10), serviceTier (default/priority)

edit_image / continue_editing

• prompt (required), imagePath (edit only), referenceImages, model, aspectRatio, resolution, numberOfImages, serviceTier

---

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](LICENSE).

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

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: notfixingit3
• Source: notfixingit3/grok-image-mcp
• License: MIT
• Homepage: https://github.com/notfixingit3/grok-image-mcp#readme

Install and usage instructions live in the source repository linked above.