Skip to main content
Glama
openrouter-image-mcp
by skelly-77

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

account_status

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.

auth_login

Starts browser sign-in. Returns at once; you finish in the browser.

auth_logout

Deletes the stored key from this machine.

list_image_models

Lists image models live from OpenRouter, with filters for search, image input, author and sort order.

get_image_model

Shows one model's real aspect ratios, resolutions, quality values, limits and pricing.

generate_image

Text to image. Saves to ~/Pictures/OpenRouter Images unless you give output_dir.

edit_image

One or more input images plus a prompt to a new image. Supports masks and exact output sizes.

remask_image

Redoes the mask blend of a masked edit_image result with a new mask. Runs locally: free, nothing uploaded.

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-tools

This installs the server config and both skills.

Claude Desktop (Windows)

  1. 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 desktop
  2. Open the config file through Settings → Developer → Edit Config and merge the openrouter-image entry into its mcpServers object (back the file up first). Use this route on the Microsoft Store (MSIX) build in particular: edits made by hand under %APPDATA%\Claude can be redirected or vanish there. The command only prints; it never edits files.

  3. 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 login

or 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

OPENROUTER_IMAGE_WORKSPACE_ID

the organization's image workspace

Workspace that sign-in creates keys in. An empty string means your personal account.

OPENROUTER_IMAGE_OUTPUT_DIR

~/Pictures/OpenRouter Images

Where generate_image saves, and the fallback when an edit's folder isn't writable. Empty means the default.

OPENROUTER_IMAGE_MAX_INPUT_EDGE

2048

Input images are downscaled to this longest edge (pixels) before upload.

OPENROUTER_IMAGE_TIMEOUT_S

600

Seconds to wait for one generation.

OPENROUTER_IMAGE_RATIO_TOLERANCE

0.03

How close (3%) a model's aspect ratio must be to the input's for fit="preserve" to crop instead of pad.

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 auth_login and sign in again.

Server won't start in Desktop, or uv errors about permissions or missing folders

Add the UV_* environment variables from print-config --client desktop (see the MSIX note above).

Sign-in doesn't stick

Check Windows Credential Manager for an entry named openrouter-image-mcp (cmdkey /list may show it as default@openrouter-image-mcp). Delete it and sign in again if it looks stale.

"Git executable not found" or "Failed to clone" when the server starts

Install Git (winget install Git.Git, or brew install git / xcode-select --install on macOS), then quit and restart Claude so it picks up the new PATH.

"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 tools
account_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

    A4.3/5.0

    Scored across 7 tools

    Disambiguation5/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness5/5

    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

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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