convez.ai
MCP ServerIntegração & APIsIntermediário
tem11134v2-cmd

OpenRouter Image MCP

tem11134v2-cmd/openrouter-image-mcp

Gere e edite imagens com 6 modelos via OpenRouter, sem configuração complexa

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor 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-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
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 5 meses
Versão
v0.3.0
Issues abertas
0
Contribuidores
1

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_path and 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, .webp detected 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, _3 suffixes 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.

AliasOpenRouter id~Cost per imageNotes
nb2 (default)google/gemini-3.1-flash-image-preview$0.07Balanced quality/speed; good text rendering; supports Google-Search grounding upstream
progoogle/gemini-3-pro-image-preview$0.07 each, typically returns 2 (≈ $0.14 / call)Best for complex compositions; multi-image variations included
flashgoogle/gemini-2.5-flash-image$0.04Legacy Nano Banana 1; lower resolution; cheapest Google option
gpt-miniopenai/gpt-5-image-mini$0.04Cheapest OpenAI tier; returns PNG
gptopenai/gpt-5-image$0.18Mid-tier OpenAI; polished "ChatGPT look"
gpt-proopenai/gpt-5.4-image-2$0.22Top-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 → flash or gpt-mini
  • Default for everyday work → nb2
  • Need text inside the image rendered cleanly → nb2 or pro
  • 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

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.exe is sometimes flaky depending on your PATH / Python setup. The client configs below use the venv's own Python with -m openrouter_image_mcp instead — 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-pro model, aspect ratio 21:9, save to ./hero.png.

Editing an existing image

Take ./photo.jpg and 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:

ParameterTypeDefaultDescription
promptstringrequiredImage description, or an edit instruction when input_image_path is set
modelstring"nb2"Alias from the table above, or any full OpenRouter model id like "google/gemini-3.1-flash-image-preview"
aspect_ratiostring | nullnullOne 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_pathstring | nullnull• 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_prefixstring | nullnullCustom stem for auto-generated filenames. Default: slug of the prompt + timestamp
input_image_pathstring | nullnullLocal 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

VarRequiredDefaultPurpose
OPENROUTER_API_KEY✅—Your OpenRouter key (sk-or-v1-...)
OUTPUT_DIR—~/openrouter-imagesDefault 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—INFOPython 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

Ver o original no GitHub

Bom para

Relacionados