OpenRouter Image MCP
tem11134v2-cmd/openrouter-image-mcp
Gere e edite imagens com 6 modelos via OpenRouter, sem configuração complexa
Ver no GitHubServidor MCP minimalista para geração e edição de imagens via OpenRouter, com suporte a 6 modelos (Google Gemini e OpenAI GPT-5). Funciona com Claude, Cursor e qualquer cliente compatível com MCP usando uma única chave API.
Instalação
npx convez-ai tem11134v2-cmd/openrouter-image-mcp1 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
Casos de uso
- Geração rápida de imagens em protótipos e drafts
- Edição de imagens existentes com prompts em IA
- Produção de assets visuais direto do Claude/Cursor
Veredito

MCP bem construído que democratiza acesso a modelos de imagem de qualidade via OpenRouter. Escolha prática para quem quer evitar complexidade de credenciais diretas no Google Cloud.
README
A tradução para o português deste README ainda está na fila.
openrouter-image-mcp
A tiny Model Context Protocol (MCP) server that lets Claude Code, Claude Desktop, Cursor, Codex and any MCP-compatible client generate or edit images via OpenRouter. One API key, six models, one tool.
Supports the current Google Nano Banana and OpenAI GPT Image families through OpenRouter's OpenAI-compatible chat-completions endpoint. No Google Cloud billing setup, no Vertex AI, no juggling vendor SDKs — just pop in your OpenRouter key and go.
Why this exists: the major Gemini-image MCP servers all require direct Google AI Studio billing, which isn't trivial to set up outside the US. OpenRouter accepts cards, PayPal and crypto, and credits never expire. This server is the thinnest possible adapter between MCP and OpenRouter.
Features
- 6 image-generation models under short aliases, plus passthrough for any full OpenRouter model id.
- Image editing — pass
input_image_pathand the same prompt becomes an edit instruction. - Aspect ratio hints — 1:1 / 16:9 / 9:16 / 21:9 / 2:3 / 3:2 / 3:4 / 4:3 / 4:5 / 5:4.
- Auto file extensions —
.png,.jpg,.webpdetected from the API response (no more mislabeled JPEGs). - Multi-image save — when a model returns several images at
once (Nano Banana Pro frequently does), they're saved with
_2,_3suffixes automatically. - Helpful errors for 401 (bad key), 402 (out of credits) and 429 (rate limited) — no cryptic stack traces.
- One dependency beyond the MCP SDK:
httpx. Install size ~50 MB.
Models
All six models speak the same chat-completions + modalities API, so
adding/removing them is a one-line change.
| Alias | OpenRouter id | ~Cost per image | Notes |
|---|---|---|---|
nb2 (default) | google/gemini-3.1-flash-image-preview | $0.07 | Balanced quality/speed; good text rendering; supports Google-Search grounding upstream |
pro | google/gemini-3-pro-image-preview | $0.07 each, typically returns 2 (≈ $0.14 / call) | Best for complex compositions; multi-image variations included |
flash | google/gemini-2.5-flash-image | $0.04 | Legacy Nano Banana 1; lower resolution; cheapest Google option |
gpt-mini | openai/gpt-5-image-mini | $0.04 | Cheapest OpenAI tier; returns PNG |
gpt | openai/gpt-5-image | $0.18 | Mid-tier OpenAI; polished "ChatGPT look" |
gpt-pro | openai/gpt-5.4-image-2 | $0.22 | Top-tier OpenAI quality; the most expensive option |
Costs are real observed amounts from the OpenRouter usage API at the time of testing. Token-based, so they vary slightly per prompt.
Picking a model:
- Quick draft / prototype →
flashorgpt-mini - Default for everyday work →
nb2 - Need text inside the image rendered cleanly →
nb2orpro - Want a couple of variations in one shot →
pro - Hero asset for publication, want maximum fidelity →
gpt-pro - Want the recognisable "ChatGPT" aesthetic →
gpt
Quick start
1. Prerequisites
- OpenRouter account with credits — sign up at https://openrouter.ai, top up at https://openrouter.ai/credits (min ~$5).
- API key from https://openrouter.ai/keys. It will start with
sk-or-v1-. uvpackage manager from Astral. On Windows:
On macOS / Linux:irm https://astral.sh/uv/install.ps1 | iexcurl -LsSf https://astral.sh/uv/install.sh | sh
2. Install the server
uv tool install --from git+https://github.com/tem11134v2-cmd/openrouter-image-mcp openrouter-image-mcp
uv will create an isolated environment, fetch Python 3.12 if you
don't have it, and install the package. Two console scripts are
exposed: openrouter-image-mcp and the launcher in ~/.local/bin/.
Windows note: the launcher in
~/.local/bin/openrouter-image-mcp.exeis sometimes flaky depending on your PATH / Python setup. The client configs below use the venv's own Python with-m openrouter_image_mcpinstead — which works reliably everywhere.
3. Wire it into your MCP client
Find the venv path that uv installed into. By default:
- Windows:
%APPDATA%\uv\tools\openrouter-image-mcp\Scripts\python.exe - macOS / Linux:
~/.local/share/uv/tools/openrouter-image-mcp/bin/python
You can confirm with:
uv tool dir
Claude Code
Edit ~/.claude.json and add to the top-level mcpServers object:
{
"mcpServers": {
"openrouter-image": {
"command": "C:/Users/YOU/AppData/Roaming/uv/tools/openrouter-image-mcp/Scripts/python.exe",
"args": ["-m", "openrouter_image_mcp"],
"env": {
"OPENROUTER_API_KEY": "sk-or-v1-...",
"OUTPUT_DIR": "C:/Users/YOU/Pictures/openrouter-images",
"X_TITLE": "My Claude Project"
}
}
}
}
Then /exit Claude Code and start it again. The tool will appear as
mcp__openrouter-image__generate_image.
Claude Desktop
Edit claude_desktop_config.json:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"openrouter-image": {
"command": "/Users/YOU/.local/share/uv/tools/openrouter-image-mcp/bin/python",
"args": ["-m", "openrouter_image_mcp"],
"env": {
"OPENROUTER_API_KEY": "sk-or-v1-...",
"OUTPUT_DIR": "/Users/YOU/Pictures/openrouter-images"
}
}
}
}
Cursor
Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json
(project-scoped):
{
"mcpServers": {
"openrouter-image": {
"command": "/path/to/uv/tools/openrouter-image-mcp/bin/python",
"args": ["-m", "openrouter_image_mcp"],
"env": {
"OPENROUTER_API_KEY": "sk-or-v1-..."
}
}
}
}
Generic MCP client (anything that takes a stdio command)
Set the same env vars in the parent shell, then run:
python -m openrouter_image_mcp
(or use the openrouter-image-mcp console script if the launcher
works on your system).
Usage
In any MCP-enabled chat:
Generate me a cinematic shot of a corgi astronaut in 16:9.
The client will call generate_image with sensible defaults. To be
explicit:
Use
gpt-promodel, aspect ratio 21:9, save to./hero.png.
Editing an existing image
Take
./photo.jpgand remove the background, keep just the subject.
Pass input_image_path="./photo.jpg" and the prompt is treated as
an edit instruction. Works with all six models.
Tool reference
The server exposes one tool, generate_image, with these
parameters:
| Parameter | Type | Default | Description |
|---|---|---|---|
prompt | string | required | Image description, or an edit instruction when input_image_path is set |
model | string | "nb2" | Alias from the table above, or any full OpenRouter model id like "google/gemini-3.1-flash-image-preview" |
aspect_ratio | string | null | null | One of 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9. Injected as a prefix into the prompt because chat-completions has no structured field for it. |
output_path | string | null | null | • Full file path with extension → exact location (multi-image gets _2, _3 suffix). • Directory path (trailing slash or no extension) → auto-named file inside. • null → OUTPUT_DIR env var, or ~/openrouter-images |
filename_prefix | string | null | null | Custom stem for auto-generated filenames. Default: slug of the prompt + timestamp |
input_image_path | string | null | null | Local path to an existing image for editing / conditioning |
Return shape:
{
"file_paths": ["C:/.../image.jpg", "C:/.../image_2.jpg"],
"model_id": "google/gemini-3.1-flash-image-preview",
"prompt": "...",
"aspect_ratio": "16:9",
"image_count": 2,
"usage": {
"prompt_tokens": 22,
"completion_tokens": 1500,
"total_tokens": 1522,
"cost": 0.06834
}
}
usage.cost is exactly what OpenRouter deducted from your balance —
great for budget tracking.
Environment variables
| Var | Required | Default | Purpose |
|---|---|---|---|
OPENROUTER_API_KEY | ✅ | — | Your OpenRouter key (sk-or-v1-...) |
OUTPUT_DIR | — | ~/openrouter-images | Default save directory when output_path is not specified |
HTTP_REFERER | — | — | Attribution header — shows up on your OpenRouter dashboard |
X_TITLE | — | — | Attribution header — human-readable project name |
LOG_LEVEL | — | INFO | Python logging level (DEBUG/INFO/WARNING/ERROR) |
Troubleshooting
401 Unauthorized — key is wrong, or you pasted it without the
sk-or-v1- prefix. OpenRouter keys are full strings starting with
that prefix.
402 Payment Required — out of credits. Top up at
https://openrouter.ai/credits.
429 Rate limited — wait a few seconds and retry. OpenRouter and
the upstream providers each have their own per-minute caps.
"OpenRouter returned no images" with no error — the upstream
model refused or rambled in text instead of generating. Try a less
ambiguous prompt or switch model (flash is the picky one).
ModuleNotFoundError: No module named 'openrouter_image_mcp' when
running the .exe launcher — on Windows, the launcher generated
by uv tool install sometimes fails to find the venv's
site-packages. This is why the configs above use the venv's
Python directly with -m openrouter_image_mcp. If you absolutely
need the launcher, reinstall with uv tool install --reinstall ...
after closing your MCP client (so file locks are released).
Want to swap your OpenRouter key without re-editing the config —
set OPENROUTER_API_KEY in the parent process environment instead;
the server picks it up the same way.
Costs in practice
A round number for budgeting: $5 of credits ≈ 70 calls on nb2
or ≈ 20 calls on gpt-pro. We deliberately kept the per-call
metadata in the response (usage.cost) so you can audit spend
without leaving your chat.
Companion skill: image-generation
This repo ships with an optional companion skill at
skills/image-generation/SKILL.md.
Drop it into ~/.claude/skills/ and any Claude session on that machine
will pick up:
- A decision tree for picking the right model per use case
- Prompt-engineering tips specific to Nano Banana / GPT Image
- Aspect-ratio guidance per use case (article hero, social, mobile, …)
- Common pitfalls (text-in-image, watermark behaviour, consistent characters)
- Mappings from typical user requests to concrete tool calls
The skill is independent of the MCP — installing one without the other is fine.
Install the skill
git clone --depth=1 https://github.com/tem11134v2-cmd/openrouter-image-mcp /tmp/oi
mkdir -p ~/.claude/skills
cp -r /tmp/oi/skills/image-generation ~/.claude/skills/
Restart Claude Code. The skill auto-activates when the user mentions generating/illustrating/drawing/editing images.
Companion repo for publishing
If you also want to publish generated images to a CDN with ready-
to-embed optimised URLs, see the sibling project:
https://github.com/tem11134v2-cmd/cloudinary-publish-mcp. It ships a
separate MCP (publish_image) and a separate image-publishing skill
that builds on top of this one.
Development
Local checkout and editable install:
git clone https://github.com/tem11134v2-cmd/openrouter-image-mcp
cd openrouter-image-mcp
uv tool install --reinstall --from . openrouter-image-mcp
The package is intentionally small — src/openrouter_image_mcp/server.py
is around 300 lines. Pull requests welcome.
License
MIT — see LICENSE.
Acknowledgments
- OpenRouter for the unified, vendor-neutral image-gen API.
- Anthropic for the Model Context Protocol and the Python MCP SDK.
- Astral for
uv, which makes Python tool installs not painful.