# Grok Image Mcp

> MCP server for Grok Imagine image generation & editing — xAI API, mock mode, Cursor/Claude compatible

- **Type:** MCP server
- **Install:** `agentstack add mcp-notfixingit3-grok-image-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [notfixingit3](https://agentstack.voostack.com/s/notfixingit3)
- **Installs:** 0
- **Category:** [Content & Media](https://agentstack.voostack.com/c/content-and-media)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [notfixingit3](https://github.com/notfixingit3)
- **Source:** https://github.com/notfixingit3/grok-image-mcp
- **Website:** https://github.com/notfixingit3/grok-image-mcp#readme

## Install

```sh
agentstack add mcp-notfixingit3-grok-image-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

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](https://github.com/notfixingit3/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.

```bash
# 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

```bash
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

```bash
./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](https://github.com/notfixingit3/grok-image-mcp/releases). 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`):

```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:

```toml
[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:**

```bash
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):

```json
{
  "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`

```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):

```json
{
  "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`):

```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`:

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

```bash
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:

```json
{
  "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`:

```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](https://console.x.ai).

---

## Environment Variables

| Variable | Required | Description |
|---|---|---|
| `XAI_API_KEY` | Live (API key mode) | xAI API key from [console.x.ai](https://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](https://github.com/notfixingit3/grok-image-mcp/releases) |
| **Docker** | `docker build -t grok-image-mcp .` |

Docker MCP config (live):

```json
{
  "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):

```json
{
  "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](https://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](https://docs.x.ai/developers/model-capabilities/imagine).

---

## 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](https://github.com/notfixingit3/nano-banana-mcpv2)
- Image API by [xAI Grok Imagine](https://docs.x.ai/developers/model-capabilities/imagine)
- Protocol by [Anthropic MCP](https://modelcontextprotocol.io)

## 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](https://github.com/notfixingit3)
- **Source:** [notfixingit3/grok-image-mcp](https://github.com/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.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-notfixingit3-grok-image-mcp
- Seller: https://agentstack.voostack.com/s/notfixingit3
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.