@stabgan/openrouter-mcp-multimodal

v4.5.3

Published

14 days ago

MCP server for OpenRouter with text chat, image analysis + generation, audio analysis + generation, video analysis, and video generation (Veo 3.1 / Sora 2 Pro / Seedance / Wan)

0High
0Medium
0Low

stabgan

mcp openrouter ai llm vision image-analysis audio transcription text-to-speech

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 | 300+ models, :nitro / :exacto suffixes, provider routing, web search, response caching, reasoning tokens | | Vision | analyze_image, generate_image | OCR, captioning, VQA, image generation with reference inputs | | Audio | analyze_audio, generate_audio | Transcription, speech/music generation | | Video | analyze_video, generate_video, generate_video_from_image, get_video_status | Clip understanding, Veo / Sora / Seedance / Wan 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, async video progress notifications, and 650+ 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 (Cursor, Claude Desktop, VS Code, etc.) — see Install 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.

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/[email protected]"]

Install uv (includes uvx), ensure Node.js 20+ 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=4.5.3 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=4.5.3 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:4.5.3

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

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

14 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.

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

Examples

Chat (free model)

{
  "tool": "chat_completion",
  "arguments": {
    "model": "google/gemma-4-26b-a4b-it:free",
    "messages": [{ "role": "user", "content": "Summarize MCP in one sentence." }]
  }
}

Analyze an image

{
  "tool": "analyze_image",
  "arguments": {
    "image_path": "diagram.png",
    "question": "List every label in this diagram."
  }
}

Use image_path and question — not image / prompt.

Search models (vision + free)

{
  "tool": "search_models",
  "arguments": {
    "query": "gemma",
    "capabilities": { "vision": true },
    "limit": 10,
    "offset": 0
  }
}

Generate video (async)

{
  "tool": "generate_video",
  "arguments": {
    "model": "google/veo-3.1",
    "prompt": "Ocean waves at sunrise, cinematic drone shot",
    "duration": 4,
    "save_path": "river.mp4"
  }
}

If the job is still running when max_wait_ms elapses, the response succeeds with _meta.code: JOB_STILL_RUNNING and a video_id — call get_video_status to resume. This is not an error.

More examples: docs/plans/tool-description-improvement.md

Security

Input path sandbox — analyze_* and reference images must stay inside OPENROUTER_INPUT_DIR
Output path sandbox — save_path must stay inside OPENROUTER_OUTPUT_DIR
SSRF protection — private/reserved IPs blocked on URL fetches
Untrusted content — analyze outputs tagged _meta.content_is_untrusted: true

Override sandboxes only with OPENROUTER_ALLOW_UNSAFE_PATHS=1 (discouraged).

Configuration

| Variable | Required | Default | Description | | :----------------------------- | :------: | :------------------------------------ | :----------------------------------- | | OPENROUTER_API_KEY | Yes | — | OpenRouter API key | | OPENROUTER_DEFAULT_MODEL | No | nvidia/nemotron-nano-12b-v2-vl:free | Default when tools omit model | | OPENROUTER_INTEGRATION_MODEL | No | google/gemma-4-26b-a4b-it:free | Model used by live integration tests | | OPENROUTER_OUTPUT_DIR | No | cwd | Sandbox root for save_path | | OPENROUTER_INPUT_DIR | No | — | Sandbox root for local input files | | OPENROUTER_LOG_LEVEL | No | info | error / warn / info / debug |

See .env.example for the full list (provider routing, image/audio/video limits, caching, video polling).

Development

git clone https://github.com/stabgan/openrouter-mcp-multimodal.git
cd openrouter-mcp-multimodal
npm install
cp .env.example .env   # add OPENROUTER_API_KEY
npm run build

Testing

Free models for CI / zero-credit accounts: integration tests default to google/gemma-4-26b-a4b-it:free (override with OPENROUTER_INTEGRATION_MODEL). GitHub Actions requires the OPENROUTER_API_KEY repository secret.

Mock tests live under src/__tests__/mock/ and cover handlers, path sandboxes, SSRF blocks, model-cache pagination, tool descriptions, and structured outputs — 330+ additional cases beyond the core suite.

npm run lint
npm run format:check

FAQ

Do I need paid OpenRouter credits?

No, to get started. Free models work for chat and vision. Audio/video generation usually requires credits; analysis may return 402 on some models — the server surfaces that as a structured error.

Which MCP clients are supported?

Any MCP-compatible client over stdio: Cursor, Claude Desktop, VS Code Copilot, Windsurf, Cline, Kiro, and custom agents.

How is this different from calling OpenRouter directly?

This server adds MCP tool schemas, security sandboxes, error taxonomy, model caching, async video polling with progress notifications, and agent-oriented tool descriptions — so LLMs invoke the right capability without custom HTTP glue.

Where is the security advisory for path traversal?

Fixed in 4.5.2+ — see GHSA-3q7p-736f-x44v and docs/solutions/security-issues/.

Compatibility

Works with any MCP client. Protocol: MCP 2025-06-18. Node ≥ 20 (Docker image uses Node 22).

License

Apache 2.0 — see LICENSE.

Contributing

Issues and PRs welcome. For large changes, open an issue first. Run npm run ci before submitting.