openrouter-mcp-multimodal

OpenRouter MCP Multimodal

The MCP server for multimodal AI agents.

One install · 19 tools · 300+ OpenRouter models · text, vision, audio & video — analysis and generation.

·

·

·

·

·

·

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:

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 770+ 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

Cursor

VS Code

Kiro

Claude Desktop / Windsurf / Cline (pick any method below)

Smithery

MCP Registry — npm + OCI packages

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

Manual config

npx (recommended)

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@4.6.2"]`

uvx / pipx (Python launcher)

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.6.2 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.6.2` pins the underlying npm package.

npm global

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

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

node (local clone)

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

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

GHCR (GitHub Container Registry)

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

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

Smithery

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

MCP Registry

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 Code CLI

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.

MCP Inspector

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

Windows npx

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?

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.

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

Environment variables

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
npm run version:check   # package.json vs src/version.ts, server.json, pyproject.toml

Releasing

Published artifacts (npm, PyPI/uvx, Docker, GHCR) all ship from the same semver on a git tag (`vX.Y.Z`). Pushing to `main` runs tests but does not publish to npm or PyPI.

Normal flow: merge conventional commits to `main` → Release Please opens a Release PR → merge it → tag is created → CI publishes everywhere.

Manual flow: bump all version files → `npm run version:check` → `npm run ci` + smoke tests → commit → `git tag vX.Y.Z` → `git push origin vX.Y.Z`.

Full checklist, file list, CI secrets, and agent instructions:

• **`docs/RELEASING.md`** — maintainer release guide
• **`AGENTS.md`** — quick reference for AI agents

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.

Before submitting: run `npm run ci`. Use Conventional Commits (`fix:`, `feat:`, etc.) so Release Please can cut the next release. See **`docs/RELEASING.md`** if you need to ship a version.