openrouter-image-mcp
This MCP server lets Claude generate, edit, and remask images with any OpenRouter image model while managing sign-in, model discovery, and cost/usage tracking.
Sign in/out of OpenRouter via browser; check key label, spending limit, and usage today/week/month/total.
Discover image models live (search, image-input filter, author, sort) and inspect one model’s aspect ratios, resolutions, quality values, limits, pricing, and provider passthrough params.
Generate images from text with model, n, aspect ratio, resolution, size, quality, seed, background, output format, output folder, filename prefix, and provider options.
Edit one or more input images with prompts, optional masks and feathering, preserve/model fit, and similar generation settings; saves next to input.
Results save locally (never overwriting) with JSON sidecars recording settings and cost; failed/cancelled generations are not charged.
Per README, remask_image can redo a masked edit’s blend locally for free from the saved unmasked layer.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@openrouter-image-mcp generate a watercolor image of a fox in a snowy forest and save it"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
openrouter-image-mcp
A local MCP server that lets Claude generate and edit images with any model on OpenRouter. Models are discovered live, nothing is hard-coded, and results are saved with a metadata sidecar and the cost shown: edits next to the input image, new images in ~/Pictures/OpenRouter Images by default.
It runs on your machine over stdio and is installed with uvx straight from this repo. You sign in once in the browser; you never see or paste an API key.
Tools
Tool | What it does |
| Shows whether you are signed in, the key's label, its usage (today, this week, this month, total) and its spending limit. It does not show the workspace. |
| Starts browser sign-in. Returns at once; you finish in the browser. |
| Deletes the stored key from this machine. |
| Lists image models live from OpenRouter, with filters for search, image input, author and sort order. |
| Shows one model's real aspect ratios, resolutions, quality values, limits and pricing. |
| Text to image. Saves to |
| One or more input images plus a prompt to a new image. Supports masks and exact output sizes. |
| Redoes the mask blend of a masked |
The skills/ folder holds two companion skills: openrouter-image (model choice, cost habits, masks, moderation) and architectural-render-polish.
Fixing a seam after a masked edit
A masked edit blends the model's image into the original through the mask. If the model drew past the mask (an arm or a shadow cut off at the edge) you can get a ghosted seam even when the new content itself is good. Since v0.2.0 every masked edit also saves the model's image before the blend as <result>.unmasked.png, at the input's exact size, and records it as unmasked_path in the sidecar (null for results made without a mask). Draw a bigger or smaller mask and ask Claude to run remask_image on the result: it re-blends that saved layer over the original input on your machine, so it costs nothing and nothing is uploaded. It needs the original input unchanged in its place, and results made by earlier versions can't be re-masked.
Related MCP server: image-generator-mcp
Prerequisites
Install uv and Git (uv uses Git to fetch the server from this repo):
winget install astral-sh.uv # Windows
winget install Git.Git # Windows
brew install uv git # macOS (or run `xcode-select --install` for Apple's Git)Open a new terminal afterwards so uvx and git are on your PATH, and restart Claude (quit it fully) after installing uv or Git so it sees them too.
Install
Claude Code
/plugin marketplace add skelly-77/openrouter-image-mcp
/plugin install openrouter-image@skelly-77-toolsThis installs the server config and both skills.
Claude Desktop (Windows)
Print a config snippet filled in with this machine's paths:
uvx --from git+https://github.com/skelly-77/openrouter-image-mcp@v0.2.0 openrouter-image-mcp print-config --client desktopOpen the config file through Settings → Developer → Edit Config and merge the
openrouter-imageentry into itsmcpServersobject (back the file up first). Use this route on the Microsoft Store (MSIX) build in particular: edits made by hand under%APPDATA%\Claudecan be redirected or vanish there. The command only prints; it never edits files.Restart Claude Desktop fully (quit from the tray icon).
Why the UV_* variables? The Microsoft Store (MSIX) build of Claude Desktop virtualizes writes under AppData, so uv's default cache, tools and Python folders can be hidden or discarded. The snippet sets UV_PYTHON_INSTALL_DIR, UV_CACHE_DIR and UV_TOOL_DIR to real folders under %USERPROFILE%\.uv, written out literally because the config file does not expand variables.
Skills for Desktop: download the repo for the release tag (v0.2.0 zip), unzip it, then zip each folder under skills/ on its own (so each zip contains the skill folder with its SKILL.md) and upload them in Settings → Capabilities.
GitHub Copilot Code (to be confirmed)
Not yet verified: the config file location, its exact format and the skills folder are still open. The standard stdio entry is below. print-config --client copilot prints the same JSON to stdout (so you can pipe or paste it) and an "unverified" note to stderr.
{
"mcpServers": {
"openrouter-image": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/skelly-77/openrouter-image-mcp@v0.2.0",
"openrouter-image-mcp"
]
}
}
}If its sandbox cannot open a browser or reach the credential store, sign in from a terminal (below).
First sign-in
Either run this in a terminal:
uvx --from git+https://github.com/skelly-77/openrouter-image-mcp@v0.2.0 openrouter-image-mcp loginor just ask Claude to run auth_login, then approve in the browser. The key is stored in your operating system's credential store (Windows Credential Manager, macOS Keychain) and nowhere else. Other commands: status, logout, login --switch (different account).
Organization billing and privacy
Keys are locked to your firm's OpenRouter organization's image workspace, so every call spends org credits, not personal ones.
Credits must be added by an org admin (account switcher → the organization → Credits) before anyone can generate. Only org admins buy credits or see billing.
Organizations are limited to 10 members by default (contact OpenRouter support for more).
Privacy: members see request metadata (model, cost, tokens, creator) for everyone's requests in the workspace, but prompt and response content only for their own requests. Org admins can view everyone's prompts and outputs.
Client renders and other uploaded images pass through OpenRouter to the model provider (for example OpenAI or Google). Get the client's or project lead's OK before uploading client imagery. The skills make Claude ask first.
Admins can set guardrails on the workspace: allowed models, budgets and data policy.
Members who leave: a member who leaves or is removed from the organization loses access to its credits and API keys. A member who still has active API keys in a workspace can't be removed from that workspace until those keys are deleted — delete their keys first (Workspace → API Keys).
Configuration
All settings are optional environment variables. Set them in the env block of the server's MCP config entry.
Variable | Default | Meaning |
| the organization's image workspace | Workspace that sign-in creates keys in. An empty string means your personal account. |
|
| Where |
|
| Input images are downscaled to this longest edge (pixels) before upload. |
|
| Seconds to wait for one generation. |
|
| How close (3%) a model's aspect ratio must be to the input's for |
Cost visibility
Each generation reports its cost and the sidecar records it. Failed or cancelled generations are not charged. Ask Claude for account_status for today's and this month's usage. Larger n and max-quality settings cost more, so iterate cheaply first.
Troubleshooting
Symptom | Fix |
401 or "not signed in" | The key was deleted or revoked. Ask Claude to run |
Server won't start in Desktop, or uv errors about permissions or missing folders | Add the |
Sign-in doesn't stick | Check Windows Credential Manager for an entry named |
"Git executable not found" or "Failed to clone" when the server starts | Install Git ( |
"Couldn't reach the OpenRouter catalog" | A network or proxy problem fetching the model list. Retry; check you can open https://openrouter.ai/api/v1/images/models in a browser. |
Moderation refusal | The model's provider declined the prompt or image. Reword the prompt, drop the flagged element, or try another model. |
Future work
A hosted remote MCP (streamable HTTP plus OAuth) would remove the need for a local uv install, but it means running a service that holds user keys, so it is out of scope for v1.
Development
uv sync
uv run pytest # unit tests, no network
uv run pytest -m live # hits real OpenRouter; sign in first
uv run ruff check
uv run python scripts/sync_plugin_skills.py # after editing skills/, refresh plugin/skills/CI runs ruff and the unit tests on Windows, macOS and Ubuntu.
License
MIT, see LICENSE.
Available Tools
7 toolsaccount_statusA
Show whether this computer is signed in to OpenRouter, with the key's spending.
Reports the key label, usage today / this week / this month / in total, and the
key's spending limit and remaining credit. If a sign-in is in progress, shows its
status and link. Use it after auth_login to confirm sign-in finished, or when the
user asks about cost, usage or credits. Takes no parameters.
Inputs: no named parameters.
auth_loginA
Sign in to OpenRouter in the user's browser.
Opens the OpenRouter sign-in page and returns at once with a link. Show the link to
the user in case the browser didn't open (it contains no secret). The user finishes
in the browser; then call account_status to confirm. The new key is stored in the
OS credential store and is never shown. Does nothing if already signed in, unless
switch_account is true.
Args: switch_account: true to sign in as a different account or workspace. The current key is kept until the new one is stored.
Inputs: switch_account.
auth_logoutA
Sign out: delete the stored OpenRouter key from this computer.
The key stays valid on OpenRouter until it is deleted on the keys dashboard; the result links that page. Takes no parameters.
Inputs: no named parameters.
edit_imageA
Edit an image (or create one from reference images) with an OpenRouter image model.
Call list_image_models first to choose a model, picking one whose inputs column
says "text+image". Options are checked against the model before anything is sent.
The input images are uploaded to a third-party model provider through OpenRouter: get the user's OK before sending client or project images to third-party providers. Each call costs money on the user's OpenRouter account; the result reports the cost.
All paths must be absolute (or start with "~"); relative paths are rejected. Results are saved next to the first input image (never overwriting it) with a JSON sidecar, unless output_dir is given. The result lists the saved paths, notes, failures, model, provider, time and cost, plus JPEG previews.
Args:
prompt: The change to make, e.g. "make it dusk with warm window light".
model: Model id from list_image_models.
images: Absolute paths of the input images. The first is the image being
edited; any others are references.
mask_path: Optional absolute path of a mask for the first image: white = change,
black = keep. The edit is composited locally, so only the white area
changes, but there may be a visible lighting seam at the mask edge where
new and old pixels meet; a soft mask edge or mask_feather_px helps.
Requires fit="preserve".
mask_feather_px: Blur radius in pixels for the mask edge; by default it is
chosen from the image size.
fit: "preserve" (default) returns each result at exactly the first input's
pixel size: the server picks the model's closest aspect ratio, then scales
and crops back (padding the input first if no ratio is close). With
fit="preserve" don't pass aspect_ratio or size. "model" keeps the size the
model returns and lets you choose aspect_ratio.
n: Number of images, 1 to 10. Above the model's max n, the server splits them
into several calls (each billed) and says so in the notes.
aspect_ratio: One of the model's aspect ratios (only with fit="model").
resolution: One of the model's resolution tiers.
size: Exact pixel size such as "1024x1024" (only with fit="model").
quality: One of the model's quality values.
seed: Integer for repeatable results, for models that support it.
background: One of the model's background values, e.g. "transparent".
output_format: One of the model's output formats, e.g. "png".
output_dir: Folder to save into instead of next to the first input. Must be
an absolute path or start with "~".
filename_prefix: File name stem; defaults to the first input's name.
provider_options: Provider passthrough options as a flat dict, e.g.
{"moderation": "low"}. Keys must be in the model's passthrough parameters
(see get_image_model); the server sends each key to every provider that
allows it. Any other key is rejected before anything is spent.
Inputs: model (required), images (required), prompt (required), n, +13 more.
generate_imageA
Generate new images from a text prompt with an OpenRouter image model.
Call list_image_models first to choose a model, and get_image_model for its exact
allowed values. Options are checked against the model before anything is sent: an
invalid value fails with the allowed values and costs nothing.
Each call costs money on the user's OpenRouter account; the result reports the cost. Prompts go to a third-party model provider through OpenRouter: get the user's OK before sending client or project images or details to third-party providers.
Images are saved (never overwriting) to the configured output folder with a JSON sidecar of the settings used. The result lists the saved paths, any notes and failures, the model, provider, time and cost, plus JPEG previews.
Args:
prompt: What to create.
model: Model id from list_image_models.
n: Number of images, 1 to 10. Above the model's max n, the server splits them
into several calls (each billed) and says so in the notes.
aspect_ratio: One of the model's aspect ratios, e.g. "16:9".
resolution: One of the model's resolution tiers.
size: Exact pixel size such as "1024x1024", for models that support it.
quality: One of the model's quality values.
seed: Integer for repeatable results, for models that support it.
background: One of the model's background values, e.g. "transparent".
output_format: One of the model's output formats, e.g. "png" or "svg".
output_dir: Folder to save into instead of the default. Must be an absolute
path or start with "~".
filename_prefix: File name stem; defaults to a slug of the prompt.
provider_options: Provider passthrough options as a flat dict, e.g.
{"moderation": "low"}. Keys must be in the model's passthrough parameters
(see get_image_model); the server sends each key to every provider that
allows it. Any other key is rejected before anything is spent.
Inputs: model (required), prompt (required), n, seed, +9 more.
get_image_modelA
Show full details for one image model.
Returns the description, the capabilities, and one section per provider endpoint
with its supported parameters and allowed values, the passthrough parameters usable
in provider_options, and its pricing line items.
Args:
model_id: Exact model id from list_image_models.
Inputs: model_id (required).
list_image_modelsA
List the image models available on OpenRouter right now, as a markdown table.
Use this before generate_image or edit_image to choose a model and see which
options it takes. The catalog is live (cached for 10 minutes), so don't rely on
remembered model ids. Columns: id, name, inputs ("text", or "text+image (max N)"
input images), aspect ratios, resolutions, quality values, max n per call, seed
support, whether the provider moderates prompts (yes/no/?), and a price summary
($/img-unit per image-output unit, $/image, or $/tok per completion token).
Call get_image_model for one model's per-provider details.
Args:
query: Case-insensitive text to find in the model id or name.
accepts_images: true for models that take input images (needed by
edit_image); false for text-only models.
author: Only this author's models: the part of the id before "/".
sort: "newest" (default, newest first) or "price" (cheapest first).
Inputs: sort, query, author, accepts_images.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
Each tool maps to a clearly distinct action: auth_login/auth_logout are opposite operations, account_status is a read-only check, list_image_models vs get_image_model cleanly separate browsing from detail lookup, and generate_image vs edit_image separate creation from modification. No meaningful overlap exists.
Most tools follow a readable verb_noun pattern (list_image_models, get_image_model, generate_image, edit_image, auth_login, auth_logout). Minor deviation: the auth group mixes prefixes ('auth_' for login/logout vs 'account_' for status), but it remains predictable.
Seven tools is well-scoped for an image-generation service: three for auth/session, two for model discovery, two for generation/editing. Every tool earns its place with no redundancy or bloat.
The surface covers the full lifecycle: sign in, verify session/spend, sign out, discover models, inspect model details, and both generate and edit images with rich parameter control. No obvious gaps for the stated domain.
Maintenance
Related MCP Connectors
Generate and edit images and create short videos inside Claude. Prepaid credits, no subscription.
Generate images and video from Claude with one API key.
Generate images from Claude, ChatGPT, Cursor and Codex with 12 top AI image models and 10 tools: up to 4 images per call, SVG vectorization, editing and more. Remote MCP with OAuth, no API keys. Pay per image, no subscription.
Generate images from Claude, ChatGPT, Cursor and Codex with 12 top AI image models. Up to 4 images per call, SVG vectorization, background removal, upscaling and image-to-video. Remote MCP with OAuth, no API keys.
Related MCP Servers
- AlicenseAqualityBmaintenanceConnects Claude Code to image generation models (OpenAI GPT Image 2, Google Nano Banana) for generating, editing, and converting images via natural language.638 npmMIT
- AlicenseAqualityDmaintenanceEnables Claude to generate and edit images using OpenAI's GPT Image models, with automatic model selection and local file saving.31MIT
- AlicenseNot gradedqualityBmaintenanceEnables Claude Code to generate and edit images through two MCP tools, routing requests to GPT Image models via a local CLIProxyAPI gateway using a ChatGPT subscription, with input validation and artifacts/receipts written to a specified directory.MIT
- AlicenseNot gradedqualityBmaintenanceEnables Claude Code to generate and iteratively refine images through OpenAI's Responses API, branching from any earlier image by its short id and using pasted screenshots, local files, URLs, or library images as references. Results are previewed in a live local gallery and stored in an iCloud-synced library with JSON sidecars for prompts, lineage, and usage.MIT