MCP Server

Active

Apache-2.0

io.github.stabgan/openrouter-multimodal MCP Server

io.github.stabgan/openrouter-multimodal

Access 300+ LLMs and multimodal AI (text, vision, audio, video) via OpenRouter in one MCP server.

What is the io.github.stabgan/openrouter-multimodal MCP server?

The OpenRouter MCP Multimodal server is a production-grade Model Context Protocol server that connects AI agents to OpenRouter's unified LLM API, providing access to 300+ language models plus multimodal capabilities for image, audio, and video analysis and generation. It exposes 14 tools covering chat, vision, audio, video, and model catalog operations with built-in security hardening and structured error handling.

This server bridges your AI coding agent (Cursor, Claude Desktop, VS Code, Windsurf, Cline) to OpenRouter's API, enabling you to chat with 300+ models and perform multimodal tasks—analyze/generate images, transcribe/generate audio, understand/generate video—all from a single install. It includes model discovery, validation, document reranking, and health checks, with production-grade input/output sandboxing and SSRF protection.

How to install io.github.stabgan/openrouter-multimodal

Copy-paste configuration for popular MCP clients.

transport: stdio

Config generated by PluginBench — verify against the source before use.

Environment / auth

OPENROUTER_API_KEY
required
secret
OpenRouter API key. Get one free at https://openrouter.ai/keys
OPENROUTER_DEFAULT_MODEL
Default model for chat + analyze tools. Defaults to nvidia/nemotron-nano-12b-v2-vl:free.
OPENROUTER_OUTPUT_DIR
Sandbox root for save_path on generate_* tools. Defaults to the current working directory.
OPENROUTER_MAX_TOKENS
Default max_tokens for chat_completion when unset in the request.
OPENROUTER_PROVIDER_SORT
price / throughput / latency
OPENROUTER_PROVIDER_IGNORE
CSV of provider slugs to exclude.
OPENROUTER_PROVIDER_ORDER
JSON array or CSV of preferred provider IDs.
OPENROUTER_PROVIDER_QUANTIZATIONS
CSV of quantization levels (fp16,int8).
OPENROUTER_PROVIDER_REQUIRE_PARAMETERS
true/false. Require providers to support all request params.
OPENROUTER_PROVIDER_DATA_COLLECTION
allow/deny
OPENROUTER_PROVIDER_ALLOW_FALLBACKS
true/false
OPENROUTER_CACHE_RESPONSES
Enable response caching server-wide. Sends X-OpenRouter-Cache: true on every chat/analyze call unless overridden per-request. Zero tokens billed on cache hits.
OPENROUTER_INCLUDE_REASONING
Enable reasoning tokens passthrough server-wide. Adds _meta.reasoning to chat_completion responses for DeepSeek R1 / Gemini Thinking / Opus 4.7.

~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "openrouter-multimodal": {
      "command": "npx",
      "args": [
        "-y",
        "@stabgan/openrouter-mcp-multimodal"
      ],
      "env": {
        "OPENROUTER_API_KEY": "<YOUR_OPENROUTER_API_KEY>",
        "OPENROUTER_DEFAULT_MODEL": "<YOUR_OPENROUTER_DEFAULT_MODEL>",
        "OPENROUTER_OUTPUT_DIR": "<YOUR_OPENROUTER_OUTPUT_DIR>",
        "OPENROUTER_MAX_TOKENS": "<YOUR_OPENROUTER_MAX_TOKENS>",
        "OPENROUTER_PROVIDER_SORT": "<YOUR_OPENROUTER_PROVIDER_SORT>",
        "OPENROUTER_PROVIDER_IGNORE": "<YOUR_OPENROUTER_PROVIDER_IGNORE>",
        "OPENROUTER_PROVIDER_ORDER": "<YOUR_OPENROUTER_PROVIDER_ORDER>",
        "OPENROUTER_PROVIDER_QUANTIZATIONS": "<YOUR_OPENROUTER_PROVIDER_QUANTIZATIONS>",
        "OPENROUTER_PROVIDER_REQUIRE_PARAMETERS": "<YOUR_OPENROUTER_PROVIDER_REQUIRE_PARAMETERS>",
        "OPENROUTER_PROVIDER_DATA_COLLECTION": "<YOUR_OPENROUTER_PROVIDER_DATA_COLLECTION>",
        "OPENROUTER_PROVIDER_ALLOW_FALLBACKS": "<YOUR_OPENROUTER_PROVIDER_ALLOW_FALLBACKS>",
        "OPENROUTER_CACHE_RESPONSES": "<YOUR_OPENROUTER_CACHE_RESPONSES>",
        "OPENROUTER_INCLUDE_REASONING": "<YOUR_OPENROUTER_INCLUDE_REASONING>"
      }
    }
  }
}

Tools & capabilities

Tools this server exposes to the agent.

chat_completion — Chat with 300+ OpenRouter models, supporting provider routing, web search, response caching, and reasoning tokens.
analyze_image — Analyze images for OCR, captioning, visual question answering, and other vision tasks.
generate_image — Generate images with optional reference inputs.
analyze_audio — Transcribe and analyze audio files.
generate_audio — Generate speech and music from text.
analyze_video — Understand and extract information from video clips.
generate_video — Generate video using models like Veo, Sora, Seedance, and Wan.
generate_video_from_image — Generate video from a static image input.
get_video_status — Check progress and status of video generation tasks.
search_models — Discover and search available OpenRouter models.
get_model_info — Retrieve detailed information about a specific model.
validate_model — Validate whether a model name is available on OpenRouter.
rerank_documents — Rerank documents using OpenRouter's reranking capability.
health_check — Check operational health of the server and OpenRouter connection.

Use cases

Chat with 300+ language models (including free options like Gemma) for coding, analysis, and creative tasks.
Analyze images for OCR, object detection, and visual question answering in your AI workflows.
Generate images and video content programmatically with reference inputs and progress tracking.
Transcribe audio and generate speech/music synthesis within your agent's context.
Discover, validate, and rerank models and documents to optimize your AI pipeline.

io.github.stabgan/openrouter-multimodal MCP server FAQ

What is the OpenRouter MCP Multimodal server?

It's an MCP server that connects AI agents to OpenRouter's API, providing access to 300+ language models plus multimodal capabilities (text, vision, audio, video) through 14 integrated tools.

Is it free to use?

OpenRouter offers a free tier with free models like google/gemma-4-26b-a4b-it:free for chat and vision. Video and audio generation typically require credits, but you can start at no cost.

How do I install it in Cursor or Claude Desktop?

Use one-click deeplinks (Cursor/VS Code/Kiro have direct buttons), or manually add the JSON config with `command: npx`, `args: ["-y", "@stabgan/openrouter-mcp-multimodal"]`, and set `OPENROUTER_API_KEY` in the env. Smithery CLI also offers interactive install.

What authentication is required?

You need an OpenRouter API key (free tier available at openrouter.ai/keys). Set it as the `OPENROUTER_API_KEY` environment variable.

Can I use it with Docker?

Yes. Run `docker run --rm -i -e OPENROUTER_API_KEY=sk-or-v1-... stabgan/openrouter-mcp-multimodal:latest` or use GHCR at `ghcr.io/stabgan/openrouter-mcp-multimodal`.

What security features does it have?

The server includes input/output path sandboxes, SSRF guards, structured error codes, and 650+ automated tests (unit, mock, regression, and live integration).

README (reference)

Source of truth, from the repository.

<img src="assets/logo.svg" alt="OpenRouter MCP Multimodal — MCP server for chat, vision, audio, and video AI tools" width="128" height="128" /> <h1 align="center">OpenRouter MCP Multimodal</h1> The MCP server for multimodal AI agents. One install · 14 tools · 300+ OpenRouter models · text, vision, audio & video — analysis and generation. <a href="https://www.npmjs.com/package/@stabgan/openrouter-mcp-multimodal"><img src="https://img.shields.io/npm/v/@stabgan/openrouter-mcp-multimodal.svg?label=npm&color=cb3837&logo=npm" alt="npm version" /></a> <a href="https://pypi.org/project/mcp-server-openrouter-multimodal/"><img src="https://img.shields.io/pypi/v/mcp-server-openrouter-multimodal.svg?label=pypi&color=3775A9&logo=pypi&logoColor=white" alt="PyPI version" /></a> <a href="https://github.com/stabgan/openrouter-mcp-multimodal/releases"><img src="https://img.shields.io/github/v/release/stabgan/openrouter-mcp-multimodal?label=release&color=6366f1" alt="GitHub release" /></a> <a href="https://hub.docker.com/r/stabgan/openrouter-mcp-multimodal"><img src="https://img.shields.io/docker/v/stabgan/openrouter-mcp-multimodal/latest?label=docker&color=2496ed&logo=docker&logoColor=white" alt="Docker version" /></a> <a href="https://github.com/stabgan/openrouter-mcp-multimodal/actions/workflows/ci.yml"><img src="https://github.com/stabgan/openrouter-mcp-multimodal/actions/workflows/ci.yml/badge.svg" alt="CI status" /></a> <a href="https://www.apache.org/licenses/LICENSE-2.0"><img src="https://img.shields.io/badge/License-Apache_2.0-blue.svg" alt="Apache 2.0 license" /></a> <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%E2%89%A520-43853d?logo=node.js&logoColor=white" alt="Node.js 20+" /></a> <a href="https://www.npmjs.com/package/@stabgan/openrouter-mcp-multimodal"><img src="https://img.shields.io/npm/dt/@stabgan/openrouter-mcp-multimodal.svg?label=npm%20downloads&color=cb3837&logo=npm" alt="npm downloads" /></a> <a href="https://hub.docker.com/r/stabgan/openrouter-mcp-multimodal"><img src="https://img.shields.io/docker/pulls/stabgan/openrouter-mcp-multimodal.svg?label=docker%20pulls&color=2496ed&logo=docker&logoColor=white" alt="Docker pulls" /></a> <a href="https://registry.modelcontextprotocol.io/servers/io.github.stabgan/openrouter-multimodal"><img src="https://img.shields.io/badge/MCP_Registry-listed-6366f1" alt="MCP Registry" /></a> <a href="https://smithery.ai/server/@stabgan/openrouter-mcp-multimodal"><img src="https://img.shields.io/badge/Smithery-Install-6366f1" alt="Smithery MCP registry" /></a> <a href="#quick-start">Quick start</a> · <a href="#tools">Tools</a> · <a href="#examples">Examples</a> · <a href="#security">Security</a> · <a href="#development">Development</a> · <a href="#faq">FAQ</a>

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.

Method	Runtime	Best for	This server
npx	Node.js 20+	Most MCP clients (default)	✅ `@stabgan/openrouter-mcp-multimodal`
uvx / pipx	Python 3.10+ and Node.js 20+	Python-first workflows, same pattern as PyPI MCP servers	✅ `mcp-server-openrouter-multimodal`
npm global	Node.js 20+	Pin a version without re-downloading	✅
node (local)	Node.js 20+	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

<table> <tr><td>Cursor</td><td><a href="https://cursor.com/en/install-mcp?name=openrouter&config=eyJ0eXBlIjoic3RkaW8iLCJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBzdGFiZ2FuL29wZW5yb3V0ZXItbWNwLW11bHRpbW9kYWwiXSwiZW52Ijp7Ik9QRU5ST1VURVJfQVBJX0tFWSI6InNrLW9yLXYxLS4uLiJ9fQ%3D%3D"><img src="https://cursor.com/deeplink/mcp-install-dark.svg" alt="Add OpenRouter MCP to Cursor" /></a></td></tr> <tr><td>VS Code</td><td><a href="https://insiders.vscode.dev/redirect/mcp/install?name=openrouter&config=%7B%22type%22%3A%22stdio%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40stabgan%2Fopenrouter-mcp-multimodal%22%5D%2C%22env%22%3A%7B%22OPENROUTER_API_KEY%22%3A%22sk-or-v1-...%22%7D%7D"><img src="https://img.shields.io/badge/Add_to-VS_Code-007ACC?style=for-the-badge&logo=visualstudiocode&logoColor=white" alt="Add to VS Code" /></a></td></tr> <tr><td>Kiro</td><td><a href="https://kiro.dev/launch/mcp/add?name=openrouter&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40stabgan%2Fopenrouter-mcp-multimodal%22%5D%2C%22env%22%3A%7B%22OPENROUTER_API_KEY%22%3A%22sk-or-v1-...%22%7D%2C%22disabled%22%3Afalse%2C%22autoApprove%22%3A%5B%5D%7D"><img src="https://img.shields.io/badge/Add_to-Kiro-232F3E?style=for-the-badge&logo=amazonaws&logoColor=white" alt="Add to Kiro" /></a></td></tr> <tr><td>Claude Desktop / Windsurf / Cline</td><td><a href="#manual-config">Manual JSON config</a> (pick any method below)</td></tr> <tr><td>Smithery</td><td><a href="https://smithery.ai/server/@stabgan/openrouter-mcp-multimodal"><code>npx -y @smithery/cli install @stabgan/openrouter-mcp-multimodal --client claude</code></a></td></tr> <tr><td>MCP Registry</td><td><a href="https://registry.modelcontextprotocol.io/servers/io.github.stabgan/openrouter-multimodal">Official registry page</a> — npm + OCI packages</td></tr> </table>

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

Manual config

<details open> <summary>npx (recommended)</summary>

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.5.3"]

</details> <details> <summary>uvx / pipx (Python launcher)</summary>

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.

</details> <details> <summary>npm global</summary>

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

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

</details> <details> <summary>node (local clone)</summary>

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-..." }
    }
  }
}

</details> <details> <summary>Docker</summary>

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

</details> <details> <summary>GHCR (GitHub Container Registry)</summary>

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"
      ]
    }
  }
}

</details> <details> <summary>Smithery</summary>

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

</details> <details> <summary>MCP Registry</summary>

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.

</details> <details> <summary>Claude Code CLI</summary>

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.

</details> <details> <summary>MCP Inspector</summary>

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

</details> <details> <summary>Windows npx</summary>

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.

</details>

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.

Tool	Purpose
`chat_completion`	Text chat, web search, provider routing, caching, reasoning
`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 with optional reference images
`generate_audio`	Text-to-speech / music
`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.

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

<details> <summary>Environment variables</summary>

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

</details>

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

Command	What it runs
`npm test`	652 unit + mock tests (no API key, <2s)
`npm run test:regression`	Security + schema regression guards
`npm run test:integration`	16 live OpenRouter scenarios (requires `.env` key)
`npm run test:e2e`	Full MCP stdio smoke (`scripts/live-e2e.mjs`)
`npm run ci`	lint + format + build + all of the above except e2e

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.

Related MCP servers

io.github.stabgan/steelmind

Maintained

Structured thinking + steel-manning verification for AI agents. Backed by 43+ papers.

TypeScript

MIT

View repository →

fomox402

Broker + MCP server for last-bidder-wins on-chain games on Solana via x402 micropayments.

View repository →

Stackin

Active

Issue and manage Brazilian fiscal documents: NF-e for goods, NFS-e for services.

Python

MIT

View repository →

StackQL MCP Server

Active

Query and provision cloud infrastructure across 40+ providers using SQL via MCP

867

MIT

View repository →

Phonebook

Active

Self-hosted gallery of SwiftUI #Preview and Jetpack Compose @Preview screens, no SaaS required.

TypeScript

MIT

View repository →

io.github.stagproject/mirelia-patent-market

Maintained

AI-optimized patent data marketplace providing structured JSON datasets.

Python

MIT

View repository →