convez.ai
MCP ServerIntegração & APIsIntermediário
notfixingit3

Grok Image MCP

notfixingit3/grok-image-mcp

Geração de imagens Grok Imagine via MCP para agentes de IA

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP que integra a geração e edição de imagens do Grok Imagine (xAI) em agentes de IA como Claude, Cursor e VS Code. Oferece modo mock gratuito para desenvolvimento e modo live com API key ou OAuth para produção.

Instalação

$npx convez-ai notfixingit3/grok-image-mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
2
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 5 meses
Versão
v0.2.0
Issues abertas
0
Contribuidores
1

Casos de uso

  • Integrar geração de imagens em fluxos de codificação com agentes IA
  • Testar workflows de imagem em modo mock sem custos
  • Editar e gerar imagens sob demanda em aplicações automatizadas

Veredito

Implementação sólida de um MCP server em Go que conecta a API de imagens do Grok Imagine a ferramentas populares. Modo mock é prático para desenvolvimento; produção requer subscription xAI ou API key, com preços moderados (~$0.02-0.05 por imagem).

README

A tradução para o português deste README ainda está na fila.

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 OAuthLive — API key
EnableGROK_IMAGE_MOCK=1grok login (uses ~/.grok/auth.json)XAI_API_KEY=...
API callsNonexAI Grok ImaginexAI Grok Imagine
CostFreeUses SuperGrok / X Premium+ quota~$0.02–$0.05 / image
Use caseDev, testing, MCP wiringSubscribers — no API key neededPay-as-you-go / teams
Config examplesexamples/ (per-client)grok-oauth-live.tomlcursor-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


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

ModelSpeedCostBest for
grok-imagine-image-quality (default)Slower$0.05/imageHigh-fidelity creative work
grok-imagine-imageFaster$0.02/imageQuick 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.

ClientConfig fileExample
Grok Build~/.grok/config.toml or .grok/config.tomlgrok-build-mock.toml
Cursor~/.cursor/mcp.json or .cursor/mcp.jsoncursor-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
OpenCodeopencode.jsonc in project root (or ~/.config/opencode/opencode.json)opencode-oauth-live.jsonc
Hermes Agent~/.hermes/config.yaml under mcp_servershermes-oauth-live.yaml
VS Code (Copilot MCP)~/Library/Application Support/Code/User/mcp.json (macOS)vscode-mcp.json
Windsurf~/.codeium/windsurf/mcp_config.jsonwindsurf-mcp.json
Dockerany client's mcpServers blocksee 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

VariableRequiredDescription
XAI_API_KEYLive (API key mode)xAI API key from console.x.ai
GROK_IMAGE_AUTHNoauto (default), oauth, or api_key
GROK_AUTH_JSONNoPath to Grok OAuth store (default: ~/.grok/auth.json)
GROK_IMAGE_MOCKNoSet to 1 for free offline mock mode
GROK_IMAGE_MODELNoDefault model (grok-imagine-image-quality)
GROK_IMAGES_DIRNoCustom output directory for saved images
GROK_IMAGE_MOCK_ASSETNoImage file used as mock output
GROK_IMAGE_LOG_FILENoOptional request/response log path

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


Available Tools

ToolDescription
generate_imageCreate a new image from a text prompt
edit_imageEdit a specific image file by path
continue_editingEdit the last image in the current session
get_last_image_infoPath, size, and timestamp of the last image
get_configuration_statusCheck API key / mock mode status
configure_xai_tokenSave an xAI API key to ~/.grok-image-config.json

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

MethodCommand
Local buildgo build -o grok-image-mcp .
Setup wizard./grok-image-mcp --setup (mock or live)
CLI help./grok-image-mcp --help / --version
Pre-built binaryGitHub Releases
Dockerdocker 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

IssueWhat to do
HTTP 403 — no credits/licensesAdd credits at console.x.ai. The server surfaces this with a direct link.
HTTP 429 — rate limitServer retries automatically (up to 3 attempts). Wait and retry, or use serviceTier: "default".
Tools not visible in clientConfirm binary path is absolute, restart/reload MCP, run grok mcp doctor grok-image-mcp (Grok Build).
No xAI key yetUse mock mode: GROK_IMAGE_MOCK=1 or ./grok-image-mcp --mock. Subscribers: run grok login instead.
OAuth 403 after loginSome tiers lack OAuth API access — set XAI_API_KEY or GROK_IMAGE_AUTH=api_key.
Empty or invalid tool argsv0.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

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

Ver o original no GitHub

Bom para

Relacionados