OpenRouter MCP Multimodal

---

What is this?

OpenRouter MCP Multimodal is a production-grade Model Context Protocol (MCP) server — listed on the official MCP Registry as io.github.stabgan/openrouter-multimodal. It connects AI coding agents (Cursor, Claude Desktop, VS Code, Windsurf, Cline, and others) to OpenRouter's unified LLM API over stdio.

Unlike text-only MCP servers, one install covers the full multimodal surface:

Capability	Tools	Highlights
Chat	chat_completion, start_chat_completion, get_chat_completion_status	300+ models, :nitro / :floor / :free / :online / :exacto suffixes, provider routing, web search, response caching, reasoning tokens, async jobs for long-running models
Vision	analyze_image, generate_image, generate_image_dedicated	OCR, captioning, VQA, image generation with reference inputs, dedicated Image API with resolution/quality/format control
Audio	analyze_audio, generate_audio, text_to_speech, speech_to_text	Transcription, speech/music generation, dedicated TTS (free Deepgram default; model-specific voices, mp3/pcm), dedicated STT (Whisper/GPT-4o Transcribe)
Video	analyze_video, generate_video, generate_video_from_image, get_video_status	Clip understanding, Veo 3.1 / Seedance 2.0 / Wan 2.7 generation with progress notifications
Catalog	search_models, get_model_info, validate_model, rerank_documents, health_check	Model discovery, validation, reranking, ops health

Production hardening: input/output path sandboxes (including analyze_* local files as of v4.5.2), SSRF guards, structured errors with _meta.code, MCP 2025-06-18 structured outputs, tool icons (2025-11-25), async video progress notifications, and 1000+ automated tests (unit, mock, regression, and live integration).

Quick start

1. Get an API key (free tier works) → openrouter.ai/keys

2. Run the server

export OPENROUTER_API_KEY=sk-or-v1-...
npx -y @stabgan/openrouter-mcp-multimodal

3. Add to your MCP client — copy one JSON block from Install into your client config:

Client	Config location
Cursor	Project: .cursor/mcp.json · User: Cursor Settings → MCP
Claude Desktop	macOS: ~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json
VS Code	.vscode/mcp.json (workspace) or User Settings → MCP
Windsurf	Windsurf Settings → MCP (same mcpServers JSON shape as Cursor)

Use the mcpServers object from Manual config below.

No credits required to start. Free models such as google/gemma-4-26b-a4b-it:free work for chat and vision. Video/audio generation typically needs credits.

Install

MCP servers are distributed through several packaging models. This server is implemented in Node.js/TypeScript; the table below maps each ecosystem method to how you run it here.

Method	Runtime	Best for	This server
npx	Node.js 22+	Most MCP clients (default)	✅ @stabgan/openrouter-mcp-multimodal
uvx / pipx	Python 3.10+ and Node.js 22+	Python-first workflows, same pattern as PyPI MCP servers	✅ mcp-server-openrouter-multimodal
npm global	Node.js 22+	Pin a version without re-downloading	✅
node (local)	Node.js 22+	Contributors / air-gapped builds	✅
Docker Hub	Docker	Isolation, no Node on host	✅ stabgan/openrouter-mcp-multimodal
GHCR	Docker	GitHub-native OCI pulls	✅ ghcr.io/stabgan/openrouter-mcp-multimodal
Smithery CLI	Node.js (via installer)	Interactive install into Claude/Cursor/etc.	✅
MCP Registry	npm or OCI	Official discovery (io.github.stabgan/openrouter-multimodal)	✅ listing
One-click deeplinks	Node.js	Cursor, VS Code, Kiro	✅
Claude Code CLI	Node.js	Terminal-first Claude Code users	✅
MCP Inspector	Node.js	Debug / list tools locally	✅
Windows cmd /c npx	Node.js	Claude Desktop / Cursor when npx not on GUI PATH	✅ see below
pip / uv (direct)	—	Native Python MCP servers only	— use uvx row above
DXT desktop extensions	—	Bundled Claude Desktop .dxt	not yet
Remote HTTP / SSE	—	Hosted Smithery / Cloudflare endpoints	via Smithery

uvx vs npx: In the MCP ecosystem, npx runs npm (Node) packages and uvx runs PyPI (Python) packages. Because this server is Node-based, uvx uses a thin Python launcher that execs npx -y @stabgan/openrouter-mcp-multimodal — you still need Node installed.

One-click

Paste your OPENROUTER_API_KEY when prompted — deeplinks use placeholders so secrets never appear in URLs.

Manual config

export OPENROUTER_API_KEY=sk-or-v1-...
npx -y @stabgan/openrouter-mcp-multimodal

{
  "mcpServers": {
    "openrouter": {
      "command": "npx",
      "args": ["-y", "@stabgan/openrouter-mcp-multimodal"],
      "env": {
        "OPENROUTER_API_KEY": "sk-or-v1-..."
      }
    }
  }
}

Pin a release: "args": ["-y", "@stabgan/openrouter-mcp-multimodal@5.0.1"]

Install uv (includes uvx), ensure Node.js 22+ is also on your PATH, then:

export OPENROUTER_API_KEY=sk-or-v1-...
uvx mcp-server-openrouter-multimodal
# pin npm version: OPENROUTER_MCP_NPM_VERSION=5.0.1 uvx mcp-server-openrouter-multimodal

{
  "mcpServers": {
    "openrouter": {
      "command": "uvx",
      "args": ["mcp-server-openrouter-multimodal"],
      "env": {
        "OPENROUTER_API_KEY": "sk-or-v1-..."
      }
    }
  }
}

pipx equivalent: pipx run mcp-server-openrouter-multimodal

Optional: OPENROUTER_MCP_NPM_VERSION=5.0.1 pins the underlying npm package.

npm install -g @stabgan/openrouter-mcp-multimodal

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

git clone https://github.com/stabgan/openrouter-mcp-multimodal.git
cd openrouter-mcp-multimodal
npm ci && npm run build

{
  "mcpServers": {
    "openrouter": {
      "command": "node",
      "args": ["/absolute/path/to/openrouter-mcp-multimodal/dist/index.js"],
      "env": { "OPENROUTER_API_KEY": "sk-or-v1-..." }
    }
  }
}

docker run --rm -i -e OPENROUTER_API_KEY=sk-or-v1-... stabgan/openrouter-mcp-multimodal:latest

{
  "mcpServers": {
    "openrouter": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "OPENROUTER_API_KEY=sk-or-v1-...",
        "stabgan/openrouter-mcp-multimodal:latest"
      ]
    }
  }
}

Use -i (interactive stdio). Avoid -t (TTY corrupts MCP framing on some hosts).

docker run --rm -i -e OPENROUTER_API_KEY=sk-or-v1-... \
  ghcr.io/stabgan/openrouter-mcp-multimodal:5.0.1

{
  "mcpServers": {
    "openrouter": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "OPENROUTER_API_KEY=sk-or-v1-...",
        "ghcr.io/stabgan/openrouter-mcp-multimodal:5.0.1"
      ]
    }
  }
}

Interactive install (writes config for your client):

npx -y @smithery/cli install @stabgan/openrouter-mcp-multimodal --client claude
# or: --client cursor | vscode | windsurf | ...

Listing: smithery.ai/server/@stabgan/openrouter-mcp-multimodal

Official name: io.github.stabgan/openrouter-multimodal

• Registry: registry.modelcontextprotocol.io
• npm package: @stabgan/openrouter-mcp-multimodal
• OCI image: docker.io/stabgan/openrouter-mcp-multimodal

Clients that support registry-driven install will offer npm or Docker; otherwise use the JSON blocks above.

claude mcp add openrouter -- npx -y @stabgan/openrouter-mcp-multimodal
# project scope:
claude mcp add --scope project openrouter -- npx -y @stabgan/openrouter-mcp-multimodal

Set OPENROUTER_API_KEY in your shell or client env before starting Claude Code.

Debug tools/list and tool calls against a live OpenRouter key:

export OPENROUTER_API_KEY=sk-or-v1-...
npx -y @modelcontextprotocol/inspector npx -y @stabgan/openrouter-mcp-multimodal

When Claude Desktop or Cursor cannot find npx (GUI apps often miss shell PATH), wrap with cmd:

{
  "mcpServers": {
    "openrouter": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@stabgan/openrouter-mcp-multimodal"],
      "env": { "OPENROUTER_API_KEY": "sk-or-v1-..." }
    }
  }
}

If still failing, use the full path from where npx as the command.

Why this server?

Capability	This server	Typical MCP LLM servers
Text chat (300+ models)	✅	✅
Image analysis + generation	✅	partial
Audio analysis + TTS	✅	❌
Video analysis + generation	✅	❌
Model search / validate / rerank	✅	❌
Path sandbox + SSRF protection	✅	rare
MCP 2025 structured outputs	✅	rare
Async video + progress notifications	✅	❌

Tools

19 MCP tools. Each description includes Use when, Good/Bad examples, Fails when, and Works with so agents pick the right tool and recover from errors.

Tool	Purpose
chat_completion	Text chat, web search, provider routing, caching, reasoning
start_chat_completion	Async background job for long-running reasoning models
get_chat_completion_status	Poll / retrieve async completion results
analyze_image	Vision — local path, URL, or data URL + question
analyze_audio	Transcribe / analyze audio files
analyze_video	Describe / Q&A over video files
generate_image	Text-to-image via chat completions with reference images
generate_image_dedicated	Text-to-image via dedicated /api/v1/images (resolution, quality, format)
generate_audio	Text-to-speech / music via chat completions
text_to_speech	Dedicated TTS (/api/v1/audio/speech) — free Deepgram default, voices, speed, mp3/pcm
speech_to_text	Dedicated STT (/api/v1/audio/transcriptions) — Whisper, GPT-4o
generate_video	Text-to-video (async, resumable)
generate_video_from_image	Image-to-video (narrower schema)
get_video_status	Poll / resume video jobs
search_models	Paginated model catalog search
get_model_info	Pricing, context, modalities
validate_model	Cheap model ID existence check
rerank_documents	Relevance ranking for RAG
health_check	API key + reachability probe

Errors use a closed _meta.code taxonomy: INVALID_INPUT · UNSAFE_PATH · UPSTREAM_* · MODEL_NOT_FOUND · JOB_STILL_RUNNING · and more.

Binary tool results (v4.7.0+)

Generate tools (generate_image, generate_image_dedicated, generate_audio, text_to_speech, generate_video, generate_video_from_image, get_video_status) return image, audio, or video bytes. As of 4.7.0 the behavior is explicit:

save_path	Tool result
Set	Text pointer only — e.g. Image saved to: out.png (… bytes, image/png) plus _meta.save_path. No inline base64 (avoids duplicating large payloads in the MCP channel).
Unset, under byte ceiling	Inline media block and summary text (images/audio use MCP image / audio types; video uses MCP resource blocks).
Unset, over ceiling	Text only with a hint to pass save_path.

Default inline ceilings (override per kind or globally):