openrouter-mcp 0.1.0

MCP stdio server and CLI for OpenRouter: model discovery, image generation/editing, and image description
openrouter-mcp-0.1.0 is not a library.

rust-openrouter-mcp

MCP (stdio) server and CLI for OpenRouter, in a single Rust binary. Discover models, generate and edit images (with parallel variants and a sidecar manifest), describe images with a vision model, and track per-process usage — all behind one openrouter-mcp executable.

Features

  • Model discovery — list_models with server-side filters (modality, supported params, sort, min context), local search, and pricing.
  • Image generation — generate_image: text-to-image, image editing / image-to-image (multiple local inputs), and parallel variants (seed-stepped).
    • The output format (PNG/JPEG) is chosen by the provider — it is sniffed from the response and the file extension is set to match.
    • Requested aspect_ratio / image_size are verified against the actual decoded pixels; mismatches are surfaced as warnings.
    • Every job writes a *.manifest.json sidecar (full settings, per-input and per-variant metadata, cost, provider, timing).
    • Asynchronous: if a job runs longer than wait_seconds (default 10) the tool returns a task_id; poll get_result for completion.
  • Image description — describe_image: image → detailed text via any vision-capable model (image input, text output).
  • Usage stats — get_usage_stats (read-only) and reset_usage_stats (destructive, requires confirm: true): per-process request/cost counters with a by-model breakdown.

Install

From a local checkout:

cargo install --path . --locked --force

From crates.io (once published):

cargo install openrouter-mcp

Configuration

Set an OpenRouter API key:

export OPENROUTER_API_KEY="sk-or-v1-..."

On PowerShell:

$env:OPENROUTER_API_KEY = "sk-or-v1-..."

A local .env file is also loaded if present (real env vars take precedence):

OPENROUTER_API_KEY=sk-or-v1-...

Do not commit .env.

Optional: OPENROUTER_IMAGE_MAX_DIMENSION (default 800) caps the longest side of input images before they are sent (downscaled to reduce request size/cost).

MCP usage

Start the stdio server (mcp subcommand is implied when none is given):

openrouter-mcp        # or: openrouter-mcp mcp

Example MCP client config:

{
  "mcpServers": {
    "openrouter": {
      "command": "openrouter-mcp",
      "env": { "OPENROUTER_API_KEY": "sk-or-v1-..." }
    }
  }
}

If the client already provides OPENROUTER_API_KEY in the environment, the env block is optional.

MCP tools

Tool Kind Description
list_models read-only List models with capabilities and pricing (server-side filters, local search).
generate_image write Generate or edit images; supports variants; async with task_id. No defaults — model, prompt, output, aspect_ratio, image_size, and image_only must all be set.
get_result read-only Fetch a job by task_id: pending / completed / failed.
describe_image read-only Describe local image(s) with a vision-capable model; returns text.
get_usage_stats read-only In-memory request/cost counters with a by-model breakdown.
reset_usage_stats destructive Reset all counters (confirm: true required).

generate_image returns a lean result — saved paths, decoded width/height, requested vs. actual aspect/size, seeds, and a pointer to the sidecar manifest; the full per-variant detail lives in the manifest on disk.

CLI usage

The same binary is a CLI. Subcommands: models, image, describe, mcp.

Browse models:

openrouter-mcp models --query openai --sort newest --table
openrouter-mcp models --output-modalities image --sort newest --table
openrouter-mcp models --query openai --search codex
openrouter-mcp models --query claude --all

Generate an image:

openrouter-mcp image \
  --model google/gemini-3.1-flash-image-preview \
  --prompt "a photorealistic owl with one cybernetic eye, starry sky" \
  --aspect-ratio 1:1 --image-size 1K --seed 1200 \
  --output ./out/owl.png

Edit / image-to-image (repeatable --image, optional label=path):

openrouter-mcp image \
  --model google/gemini-3.1-flash-image-preview \
  --prompt "add a small wizard hat" \
  --image ./out/owl.png \
  --output ./out/owl-hat.png

Four parallel variants (files named *-var-<seed>.<ext> plus a manifest):

openrouter-mcp image -m bytedance-seed/seedream-4.5 --image-only \
  --prompt "a cute pixar-style baby dragon" \
  --aspect-ratio 1:1 --image-size 1K --seed 1490 --variants 4 \
  --output ./out/dragon.png

Describe an image:

openrouter-mcp describe -m google/gemini-2.5-flash-lite --image ./out/owl.png

The image format the provider returns is not guaranteed; the CLI corrects the saved file's extension to match what actually came back.

Development

cargo fmt --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test
cargo llvm-cov --summary-only        # coverage (cargo install cargo-llvm-cov)

Live smoke tests (require OPENROUTER_API_KEY):

cargo run -- models --query openai --sort newest --table
cargo run -- describe -m google/gemini-2.5-flash-lite --image ./some.png

License

Licensed under either of:

at your option.