Skip to content
Back to search

openrouter-mcp-multimodal

MCP server for OpenRouter — chat with 300+ LLMs (Claude, Gemini, GPT), analyze images / audio / video, generate images / speech / music / video (Veo 3.1, Sora, Seedance, Wan) from Claude Desktop, Cursor, Kiro, VS Code.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/stabgan/openrouter-mcp-multimodal with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/stabgan/openrouter-mcp-multimodal'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/stabgan--openrouter-mcp-multimodal/badge.svg)](/listings/stabgan--openrouter-mcp-multimodal)

HTML

<a href="/listings/stabgan--openrouter-mcp-multimodal"><img src="/api/listings/stabgan--openrouter-mcp-multimodal/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

**1. Get an API key** (free tier works) → [openrouter.ai/keys](https://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](#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](#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.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 690 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <p align="center">
  2. <img src="assets/logo.png" alt="OpenRouter MCP Multimodal — MCP server for chat, vision, audio, and video AI tools" width="128" height="128" />
  3. </p>
  4. <h1 align="center">OpenRouter MCP Multimodal</h1>
  5. <p align="center">
  6. <strong>The MCP server for multimodal AI agents.</strong><br/>
  7. One install · 21 tools · 300+ OpenRouter models · text, vision, audio &amp; video — analysis and generation.
  8. </p>
  9. <p align="center">
  10. <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>
  11. <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>
  12. <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>
  13. <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>
  14. <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>
  15. <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>
  16. <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%E2%89%A522-43853d?logo=node.js&logoColor=white" alt="Node.js 22+" /></a>
  17. </p>
  18. <p align="center">
  19. <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>
  20. <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>
  21. <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>
  22. <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>
  23. </p>
  24. <p align="center">
  25. <a href="#quick-start">Quick start</a> ·
  26. <a href="#tools">Tools</a> ·
  27. <a href="#examples">Examples</a> ·
  28. <a href="#security">Security</a> ·
  29. <a href="#troubleshooting">Troubleshooting</a> ·
  30. <a href="#development">Development</a> ·
  31. <a href="#releasing">Releasing</a> ·
  32. <a href="#faq">FAQ</a>
  33. </p>
  34. ---
  35. ## What is this?
  36. **OpenRouter MCP Multimodal** is a production-grade [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server — listed on the [official MCP Registry](https://registry.modelcontextprotocol.io/servers/io.github.stabgan/openrouter-multimodal) as `io.github.stabgan/openrouter-multimodal`. It connects AI coding agents ([Cursor](https://cursor.com), [Claude Desktop](https://claude.ai/download), [VS Code](https://code.visualstudio.com), [Windsurf](https://codeium.com/windsurf), [Cline](https://github.com/cline/cline), and others) to [OpenRouter](https://openrouter.ai)'s unified LLM API over stdio.
  37. Unlike text-only MCP servers, one install covers the **full multimodal surface**:
  38. | Capability | Tools | Highlights |
  39. | :------------ | :-------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  40. | **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, reasoning effort control, structured output (JSON Schema), async jobs, multi-model fusion, subagent delegation, response healing |
  41. | **Vision** | `analyze_image`, `generate_image`, `generate_image_dedicated` | OCR, captioning, VQA, image generation with reference inputs, dedicated Image API with resolution/quality/format control |
  42. | **Audio** | `analyze_audio`, `generate_audio`, `text_to_speech`, `speech_to_text` | Transcription, speech/music generation, dedicated TTS (Deepgram, ElevenLabs, OpenAI; free Deepgram default, voices, mp3/pcm), dedicated STT (Whisper, GPT-4o Transcribe, Voxtral, ElevenLabs Scribe) |
  43. | **Video** | `analyze_video`, `generate_video`, `generate_video_from_image`, `get_video_status` | Clip understanding, Veo 3.1 / Seedance 2.5 / Kling v3.0 / Wan 2.7 / Grok Imagine Video generation with progress notifications |
  44. | **Embedding** | `embed_text` | 37+ embedding models (text-embedding-3-small/large, Nomic, Jina, Voyage, etc.) |
  45. | **Decisions** | `decide` | Structured yes/no, choice, or score decisions with calibrated probabilities (System One models) |
  46. | **Catalog** | `search_models`, `get_model_info`, `validate_model`, `rerank_documents`, `health_check` | Model discovery, validation, reranking, ops health |
  47. **Production hardening:** input/output path sandboxes (including analyze\_\* local files as of v4.5.2), SSRF guards, structured errors with `_meta.code`, MCP 2025-11-25 structured outputs + tool icons, async video progress notifications, and **3929** automated tests (3905 unit/mock + 7 regression + 17 live integration).
  48. ## Quick start
  49. **1. Get an API key** (free tier works) → [openrouter.ai/keys](https://openrouter.ai/keys)
  50. **2. Run the server**
  51. ```bash
  52. export OPENROUTER_API_KEY=sk-or-v1-...
  53. npx -y @stabgan/openrouter-mcp-multimodal
  54. ```
  55. **3. Add to your MCP client** — copy one JSON block from [Install](#install) into your client config:
  56. | Client | Config location |
  57. | :----------------- | :-------------------------------------------------------------------------------------------------------------------------------- |
  58. | **Cursor** | Project: `.cursor/mcp.json` · User: Cursor Settings → MCP |
  59. | **Claude Desktop** | macOS: `~/Library/Application Support/Claude/claude_desktop_config.json` · Windows: `%APPDATA%\Claude\claude_desktop_config.json` |
  60. | **VS Code** | `.vscode/mcp.json` (workspace) or User Settings → MCP |
  61. | **Windsurf** | Windsurf Settings → MCP (same `mcpServers` JSON shape as Cursor) |
  62. Use the `mcpServers` object from [Manual config](#manual-config) below.
  63. > **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.
  64. ## Install
  65. 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.
  66. | Method | Runtime | Best for | This server |
  67. | :-------------------------------------- | :------------------------------- | :------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------- |
  68. | **[npx](#manual-config)** | Node.js 22+ | Most MCP clients (default) | ✅ `@stabgan/openrouter-mcp-multimodal` |
  69. | **[uvx / pipx](#manual-config)** | Python 3.10+ **and** Node.js 22+ | Python-first workflows, same pattern as PyPI MCP servers | ✅ [`mcp-server-openrouter-multimodal`](https://pypi.org/project/mcp-server-openrouter-multimodal/) |
  70. | **[npm global](#manual-config)** | Node.js 22+ | Pin a version without re-downloading | ✅ |
  71. | **[node (local)](#manual-config)** | Node.js 22+ | Contributors / air-gapped builds | ✅ |
  72. | **[Docker Hub](#manual-config)** | Docker | Isolation, no Node on host | ✅ `stabgan/openrouter-mcp-multimodal` |
  73. | **[GHCR](#manual-config)** | Docker | GitHub-native OCI pulls | ✅ `ghcr.io/stabgan/openrouter-mcp-multimodal` |
  74. | **[Smithery CLI](#smithery)** | Node.js (via installer) | Interactive install into Claude/Cursor/etc. | ✅ |
  75. | **[MCP Registry](#mcp-registry)** | npm or OCI | Official discovery (`io.github.stabgan/openrouter-multimodal`) | ✅ [listing](https://registry.modelcontextprotocol.io/servers/io.github.stabgan/openrouter-multimodal) |
  76. | **[One-click deeplinks](#one-click)** | Node.js | Cursor, VS Code, Kiro | ✅ |
  77. | **[Claude Code CLI](#claude-code-cli)** | Node.js | Terminal-first Claude Code users | ✅ |
  78. | **[MCP Inspector](#mcp-inspector)** | Node.js | Debug / list tools locally | ✅ |
  79. | **Windows `cmd /c npx`** | Node.js | Claude Desktop / Cursor when `npx` not on GUI PATH | ✅ [see below](#windows-npx) |
  80. | pip / uv (direct) | — | Native Python MCP servers only | — use **uvx** row above |
  81. | DXT desktop extensions | — | Bundled Claude Desktop `.dxt` | not yet |
  82. | Remote HTTP / SSE | — | Hosted Smithery / Cloudflare endpoints | via [Smithery](https://smithery.ai/server/@stabgan/openrouter-mcp-multimodal) |
  83. > **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](./python/) that execs `npx -y @stabgan/openrouter-mcp-multimodal` — you still need Node installed.
  84. ### One-click
  85. <table>
  86. <tr><td><strong>Cursor</strong></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>
  87. <tr><td><strong>VS Code</strong></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>
  88. <tr><td><strong>Kiro</strong></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>
  89. <tr><td><strong>Claude Desktop / Windsurf / Cline</strong></td><td><a href="#manual-config">Manual JSON config</a> (pick any method below)</td></tr>
  90. <tr><td><strong>Smithery</strong></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>
  91. <tr><td><strong>MCP Registry</strong></td><td><a href="https://registry.modelcontextprotocol.io/servers/io.github.stabgan/openrouter-multimodal">Official registry page</a> — npm + OCI packages</td></tr>
  92. </table>
  93. Paste your `OPENROUTER_API_KEY` when prompted — deeplinks use placeholders so secrets never appear in URLs.
  94. ### Manual config
  95. <details open>
  96. <summary><strong>npx (recommended)</strong></summary>
  97. ```bash
  98. export OPENROUTER_API_KEY=sk-or-v1-...
  99. npx -y @stabgan/openrouter-mcp-multimodal
  100. ```
  101. ```json
  102. {
  103. "mcpServers": {
  104. "openrouter": {
  105. "command": "npx",
  106. "args": ["-y", "@stabgan/openrouter-mcp-multimodal"],
  107. "env": {
  108. "OPENROUTER_API_KEY": "sk-or-v1-..."
  109. }
  110. }
  111. }
  112. }
  113. ```
  114. Pin a release: `"args": ["-y", "@stabgan/openrouter-mcp-multimodal@5.1.3"]`
  115. </details>
  116. <details>
  117. <summary><strong>uvx / pipx (Python launcher)</strong></summary>
  118. Install [uv](https://docs.astral.sh/uv/getting-started/installation/) (includes `uvx`), ensure **Node.js 22+** is also on your `PATH`, then:
  119. ```bash
  120. export OPENROUTER_API_KEY=sk-or-v1-...
  121. uvx mcp-server-openrouter-multimodal
  122. # pin npm version: OPENROUTER_MCP_NPM_VERSION=5.1.3 uvx mcp-server-openrouter-multimodal
  123. ```
  124. ```json
  125. {
  126. "mcpServers": {
  127. "openrouter": {
  128. "command": "uvx",
  129. "args": ["mcp-server-openrouter-multimodal"],
  130. "env": {
  131. "OPENROUTER_API_KEY": "sk-or-v1-..."
  132. }
  133. }
  134. }
  135. }
  136. ```
  137. **pipx equivalent:** `pipx run mcp-server-openrouter-multimodal`
  138. Optional: `OPENROUTER_MCP_NPM_VERSION=5.1.3` pins the underlying npm package.
  139. </details>
  140. <details>
  141. <summary><strong>npm global</strong></summary>
  142. ```bash
  143. npm install -g @stabgan/openrouter-mcp-multimodal
  144. ```
  145. ```json
  146. {
  147. "mcpServers": {
  148. "openrouter": {
  149. "command": "openrouter-multimodal",
  150. "env": { "OPENROUTER_API_KEY": "sk-or-v1-..." }
  151. }
  152. }
  153. }
  154. ```
  155. </details>
  156. <details>
  157. <summary><strong>node (local clone)</strong></summary>
  158. ```bash
  159. git clone https://github.com/stabgan/openrouter-mcp-multimodal.git
  160. cd openrouter-mcp-multimodal
  161. npm ci && npm run build
  162. ```
  163. ```json
  164. {
  165. "mcpServers": {
  166. "openrouter": {
  167. "command": "node",
  168. "args": ["/absolute/path/to/openrouter-mcp-multimodal/dist/index.js"],
  169. "env": { "OPENROUTER_API_KEY": "sk-or-v1-..." }
  170. }
  171. }
  172. }
  173. ```
  174. </details>
  175. <details>
  176. <summary><strong>Docker</strong></summary>
  177. ```bash
  178. docker run --rm -i -e OPENROUTER_API_KEY=sk-or-v1-... stabgan/openrouter-mcp-multimodal:latest
  179. ```
  180. ```json
  181. {
  182. "mcpServers": {
  183. "openrouter": {
  184. "command": "docker",
  185. "args": [
  186. "run",
  187. "--rm",
  188. "-i",
  189. "-e",
  190. "OPENROUTER_API_KEY=sk-or-v1-...",
  191. "stabgan/openrouter-mcp-multimodal:latest"
  192. ]
  193. }
  194. }
  195. }
  196. ```
  197. Use `-i` (interactive stdio). Avoid `-t` (TTY corrupts MCP framing on some hosts).
  198. </details>
  199. <details>
  200. <summary><strong>GHCR (GitHub Container Registry)</strong></summary>
  201. ```bash
  202. docker run --rm -i -e OPENROUTER_API_KEY=sk-or-v1-... \
  203. ghcr.io/stabgan/openrouter-mcp-multimodal:5.1.3
  204. ```
  205. ```json
  206. {
  207. "mcpServers": {
  208. "openrouter": {
  209. "command": "docker",
  210. "args": [
  211. "run",
  212. "--rm",
  213. "-i",
  214. "-e",
  215. "OPENROUTER_API_KEY=sk-or-v1-...",
  216. "ghcr.io/stabgan/openrouter-mcp-multimodal:5.1.3"
  217. ]
  218. }
  219. }
  220. }
  221. ```
  222. </details>
  223. <details>
  224. <summary><strong>Smithery</strong></summary>
  225. Interactive install (writes config for your client):
  226. ```bash
  227. npx -y @smithery/cli install @stabgan/openrouter-mcp-multimodal --client claude
  228. # or: --client cursor | vscode | windsurf | ...
  229. ```
  230. Listing: [smithery.ai/server/@stabgan/openrouter-mcp-multimodal](https://smithery.ai/server/@stabgan/openrouter-mcp-multimodal)
  231. </details>
  232. <details>
  233. <summary><strong>MCP Registry</strong></summary>
  234. Official name: `io.github.stabgan/openrouter-multimodal`
  235. - Registry: [registry.modelcontextprotocol.io](https://registry.modelcontextprotocol.io/servers/io.github.stabgan/openrouter-multimodal)
  236. - npm package: `@stabgan/openrouter-mcp-multimodal`
  237. - OCI image: `docker.io/stabgan/openrouter-mcp-multimodal`
  238. Clients that support registry-driven install will offer npm or Docker; otherwise use the JSON blocks above.
  239. </details>
  240. <details>
  241. <summary><strong>Claude Code CLI</strong></summary>
  242. ```bash
  243. claude mcp add openrouter -- npx -y @stabgan/openrouter-mcp-multimodal
  244. # project scope:
  245. claude mcp add --scope project openrouter -- npx -y @stabgan/openrouter-mcp-multimodal
  246. ```
  247. Set `OPENROUTER_API_KEY` in your shell or client env before starting Claude Code.
  248. </details>
  249. <details>
  250. <summary><strong>MCP Inspector</strong></summary>
  251. Debug tools/list and tool calls against a live OpenRouter key:
  252. ```bash
  253. export OPENROUTER_API_KEY=sk-or-v1-...
  254. npx -y @modelcontextprotocol/inspector npx -y @stabgan/openrouter-mcp-multimodal
  255. ```
  256. </details>
  257. <details>
  258. <summary><strong>Windows npx</strong></summary>
  259. When Claude Desktop or Cursor cannot find `npx` (GUI apps often miss shell `PATH`), wrap with `cmd`:
  260. ```json
  261. {
  262. "mcpServers": {
  263. "openrouter": {
  264. "command": "cmd",
  265. "args": ["/c", "npx", "-y", "@stabgan/openrouter-mcp-multimodal"],
  266. "env": { "OPENROUTER_API_KEY": "sk-or-v1-..." }
  267. }
  268. }
  269. }
  270. ```
  271. If still failing, use the full path from `where npx` as the command.
  272. </details>
  273. ## Why this server?
  274. | Capability | This server | Typical MCP LLM servers |
  275. | :----------------------------------- | :---------: | :---------------------: |
  276. | Text chat (300+ models) | ✅ | ✅ |
  277. | Image analysis + generation | ✅ | partial |
  278. | Audio analysis + TTS + STT | ✅ | ❌ |
  279. | Video analysis + generation | ✅ | ❌ |
  280. | Vector embeddings (37+ models) | ✅ | ❌ |
  281. | Structured decisions (System One) | ✅ | ❌ |
  282. | Model search / validate / rerank | ✅ | ❌ |
  283. | Path sandbox + SSRF protection | ✅ | rare |
  284. | MCP 2025 structured outputs | ✅ | rare |
  285. | Async video + progress notifications | ✅ | ❌ |
  286. ## Tools
  287. 21 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.
  288. | Tool | Purpose |
  289. | :--------------------------- | :------------------------------------------------------------------------------------- |
  290. | `chat_completion` | Text chat, web search, provider routing, caching, reasoning, structured output |
  291. | `start_chat_completion` | Async background job for long-running reasoning models |
  292. | `get_chat_completion_status` | Poll / retrieve async completion results |
  293. | `analyze_image` | Vision — local path, URL, or data URL + `question` |
  294. | `analyze_audio` | Transcribe / analyze audio files |
  295. | `analyze_video` | Describe / Q&A over video files |
  296. | `generate_image` | Text-to-image via chat completions with reference images |
  297. | `generate_image_dedicated` | Text-to-image via dedicated `/api/v1/images` (resolution, quality, format) |
  298. | `generate_audio` | Text-to-speech / music via chat completions |
  299. | `text_to_speech` | Dedicated TTS (`/api/v1/audio/speech`) — Deepgram, ElevenLabs, OpenAI; voices, speed, mp3/pcm |
  300. | `speech_to_text` | Dedicated STT (`/api/v1/audio/transcriptions`) — Whisper, GPT-4o Transcribe, Voxtral, ElevenLabs Scribe |
  301. | `generate_video` | Text-to-video (async, resumable) |
  302. | `generate_video_from_image` | Image-to-video (narrower schema) |
  303. | `get_video_status` | Poll / resume video jobs |
  304. | `search_models` | Paginated model catalog search |
  305. | `get_model_info` | Pricing, context, modalities |
  306. | `validate_model` | Cheap model ID existence check |
  307. | `rerank_documents` | Relevance ranking for RAG |
  308. | `embed_text` | Vector embeddings (37+ models: text-embedding-3-small/large, Nomic, etc.) |
  309. | `decide` | Structured decisions with calibrated probabilities (System One models) |
  310. | `health_check` | API key + reachability probe |
  311. Every error carries `_meta.code` from a closed taxonomy (13 codes). Switch on these for programmatic handling:
  312. | `_meta.code` | Meaning | Recovery |
  313. | :-------------------- | :-------------------------------------------------- | :---------------------------------------------------------------- |
  314. | `INVALID_INPUT` | Bad or missing arguments | Check tool description for correct schema |
  315. | `INVALID_CREDENTIALS` | API key missing, invalid, or revoked | Regenerate at [openrouter.ai/keys](https://openrouter.ai/keys) |
  316. | `UNSAFE_PATH` | Local path escaped the input/output sandbox | Move files under `OPENROUTER_INPUT_DIR` / `OPENROUTER_OUTPUT_DIR` |
  317. | `UPSTREAM_HTTP` | Non-auth HTTP error from OpenRouter (4xx/5xx) | Check `_meta.details.status`; retry if transient |
  318. | `UPSTREAM_TIMEOUT` | Upstream did not respond in time | Retry, or use `start_chat_completion` for slow models |
  319. | `UPSTREAM_REFUSED` | Content policy, rate limit, or insufficient credits | Check `_meta.retry_after_seconds`; review prompt or add credits |
  320. | `UNSUPPORTED_FORMAT` | File is not a recognized media format | Verify file type matches tool expectations |
  321. | `RESOURCE_TOO_LARGE` | File exceeds fetch/inline size cap | Trim file or use `save_path` to skip inline |
  322. | `ZDR_INCOMPATIBLE` | Model/provider requires zero data retention | Use a ZDR-compatible provider or different model |
  323. | `MODEL_NOT_FOUND` | Model slug not in OpenRouter catalog | Run `validate_model` or `search_models` first |
  324. | `JOB_FAILED` | Async job (video/chat) failed on provider side | Check `_meta.details`; retry or change model |
  325. | `JOB_STILL_RUNNING` | Async job not yet complete (not an error) | Call `get_video_status` / `get_chat_completion_status` to poll |
  326. | `INTERNAL` | Unexpected server-side error | Report if reproducible |
  327. Errors include `_meta.suggestions` with agent-oriented next steps when available.
  328. ### Binary tool results (v4.7.0+)
  329. 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:
  330. | `save_path` | Tool result |
  331. | :---------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  332. | **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). |
  333. | **Unset, under byte ceiling** | Inline media block **and** summary text (images/audio use MCP `image` / `audio` types; video uses MCP `resource` blocks). |
  334. | **Unset, over ceiling** | Text only with a hint to pass `save_path`. |
  335. Default inline ceilings (override per kind or globally):
  336. | Kind | Default | Env vars (precedence: per-kind → global) |
  337. | :---- | :------ | :------------------------------------------------------------------ |
  338. | Image | 1 MiB | `OPENROUTER_IMAGE_INLINE_MAX_BYTES` → `OPENROUTER_INLINE_MAX_BYTES` |
  339. | Audio | 1 MiB | `OPENROUTER_AUDIO_INLINE_MAX_BYTES` → `OPENROUTER_INLINE_MAX_BYTES` |
  340. | Video | 10 MiB | `OPENROUTER_VIDEO_INLINE_MAX_BYTES` → `OPENROUTER_INLINE_MAX_BYTES` |
  341. If you previously relied on **both** a saved file **and** inline media in the same tool result, read the file from `_meta.save_path` (or omit `save_path` to get inline media when under the ceiling).
  342. ## Examples
  343. ### Chat (free model)
  344. ```json
  345. {
  346. "tool": "chat_completion",
  347. "arguments": {
  348. "model": "google/gemma-4-26b-a4b-it:free",
  349. "messages": [{ "role": "user", "content": "Summarize MCP in one sentence." }]
  350. }
  351. }
  352. ```
  353. ### Chat with structured output (JSON Schema)
  354. ```json
  355. {
  356. "tool": "chat_completion",
  357. "arguments": {
  358. "model": "openai/gpt-4o",
  359. "messages": [{ "role": "user", "content": "Extract the name and age from: 'Alice is 30 years old.'" }],
  360. "response_format": {
  361. "type": "json_schema",
  362. "json_schema": {
  363. "name": "person",
  364. "schema": {
  365. "type": "object",
  366. "properties": {
  367. "name": { "type": "string" },
  368. "age": { "type": "integer" }
  369. },
  370. "required": ["name", "age"]
  371. }
  372. }
  373. }
  374. }
  375. }
  376. ```
  377. > For simpler JSON without a schema, use `"response_format": { "type": "json_object" }`. Add `"response_healing": true` to auto-fix malformed JSON.
  378. ### Analyze an image
  379. ```json
  380. {
  381. "tool": "analyze_image",
  382. "arguments": {
  383. "image_path": "diagram.png",
  384. "question": "List every label in this diagram."
  385. }
  386. }
  387. ```
  388. > Use `image_path` and `question` — not `image` / `prompt`.
  389. ### Search models (vision + free)
  390. ```json
  391. {
  392. "tool": "search_models",
  393. "arguments": {
  394. "query": "gemma",
  395. "capabilities": { "vision": true },
  396. "limit": 10,
  397. "offset": 0
  398. }
  399. }
  400. ```
  401. ### Generate video (async)
  402. ```json
  403. {
  404. "tool": "generate_video",
  405. "arguments": {
  406. "model": "google/veo-3.1",
  407. "prompt": "Ocean waves at sunrise, cinematic drone shot",
  408. "duration": 4,
  409. "save_path": "river.mp4"
  410. }
  411. }
  412. ```
  413. 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.**
  414. With `save_path` set (as above), the result is a **text pointer** to the saved file once complete — not inline video. See [Binary tool results](#binary-tool-results-v470).
  415. ### Embed text (vector embeddings)
  416. ```json
  417. {
  418. "tool": "embed_text",
  419. "arguments": {
  420. "texts": ["What is MCP?", "Model Context Protocol enables tool use for LLMs."],
  421. "model": "openai/text-embedding-3-small",
  422. "dimensions": 1024
  423. }
  424. }
  425. ```
  426. Returns embedding arrays for RAG, semantic search, or clustering. 37+ models supported — pass a single string or an array of up to 2048 texts.
  427. ### Structured decision (System One)
  428. ```json
  429. {
  430. "tool": "decide",
  431. "arguments": {
  432. "questions": {
  433. "is_bug": {
  434. "type": "noul",
  435. "instructions": "Is this a bug report or a feature request?",
  436. "criteria": {
  437. "true": "Describes broken or incorrect behavior",
  438. "false": "Requests new functionality"
  439. }
  440. }
  441. },
  442. "state": {
  443. "ticket": "The login button does not respond when clicked on Safari."
  444. }
  445. }
  446. }
  447. ```
  448. Returns calibrated probabilities instead of generated text. Three question types: `noul` (yes/no), `choice` (pick one category), `score` (ordinal rubric). Models: `typesafe/jev-1.13` (default), `upstage/solar-decide`, `microsoft/decision-1`.
  449. More examples: [docs/plans/tool-description-improvement.md](./docs/plans/tool-description-improvement.md)
  450. ## Security
  451. - **Input path sandbox** — local paths on `analyze_*` and reference images must stay inside `OPENROUTER_INPUT_DIR` (falls back to `OPENROUTER_OUTPUT_DIR`, then `cwd`)
  452. - **Output path sandbox** — `save_path` must stay inside `OPENROUTER_OUTPUT_DIR`
  453. - **Async job reads** — `get_chat_completion_status` resolves disk paths only under `OPENROUTER_OUTPUT_DIR/openrouter-jobs/` (4.7.0+)
  454. - **SSRF protection** — private/reserved IPs blocked on URL fetches
  455. - **Untrusted content** — analyze outputs tagged `_meta.content_is_untrusted: true`
  456. - **Prototype-pollution defense** — all API output boundaries (model records, embeddings, decisions, rerank results, log context) recursively strip `__proto__`, `constructor`, and `prototype` keys before forwarding to MCP clients
  457. - **Secret redaction** — the stderr JSON logger redacts API keys and sensitive values; stdout is reserved for MCP protocol traffic
  458. Override sandboxes only with `OPENROUTER_ALLOW_UNSAFE_PATHS=1` (discouraged).
  459. Report vulnerabilities: **[SECURITY.md](./SECURITY.md)** (private disclosure — do not file public issues for exploits).
  460. ## Configuration
  461. <details>
  462. <summary><strong>Environment variables</strong></summary>
  463. | Variable | Required | Default | Description |
  464. | :---------------------------------- | :------: | :------------------------------- | :---------------------------------- |
  465. | `OPENROUTER_API_KEY` | **Yes** | — | OpenRouter API key |
  466. | `OPENROUTER_DEFAULT_MODEL` | No | `google/gemma-4-26b-a4b-it:free` | Default when tools omit `model` |
  467. | `OPENROUTER_OUTPUT_DIR` | No | `cwd` | Sandbox root for `save_path` |
  468. | `OPENROUTER_INPUT_DIR` | No | `OUTPUT_DIR` or `cwd` | Sandbox root for local input files |
  469. | `OPENROUTER_INLINE_MAX_BYTES` | No | `1048576` (image/audio) | Global inline media ceiling |
  470. | `OPENROUTER_IMAGE_INLINE_MAX_BYTES` | No | falls back to global | Per-kind inline ceiling |
  471. | `OPENROUTER_AUDIO_INLINE_MAX_BYTES` | No | falls back to global | Per-kind inline ceiling |
  472. | `OPENROUTER_VIDEO_INLINE_MAX_BYTES` | No | `10485760` | Video inline ceiling |
  473. | `OPENROUTER_LOG_LEVEL` | No | `info` | `error` / `warn` / `info` / `debug` |
  474. See [`.env.example`](./.env.example) for the full list (provider routing, fetch limits, caching, video polling, async jobs, integration-test overrides).
  475. </details>
  476. ## Development
  477. ```bash
  478. git clone https://github.com/stabgan/openrouter-mcp-multimodal.git
  479. cd openrouter-mcp-multimodal
  480. npm install
  481. cp .env.example .env # add OPENROUTER_API_KEY
  482. npm run build
  483. ```
  484. ### Testing
  485. | Command | What it runs |
  486. | :------------------------- | :--------------------------------------------------------- |
  487. | `npm test` | **3905** unit + mock tests (no API key, &lt;20s) |
  488. | `npm run test:regression` | **7** security + schema regression guards |
  489. | `npm run test:integration` | **17** live OpenRouter scenarios (**requires** `.env` key) |
  490. | `npm run test:e2e` | Full MCP stdio smoke (`scripts/live-e2e.mjs`) |
  491. | `npm run ci` | lint + format + version sync + build + **all** tests |
  492. **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.
  493. Mock tests live under `src/__tests__/mock/` and cover handlers, path sandboxes, SSRF blocks, model-cache pagination, tool descriptions, and structured outputs — **396** additional cases beyond the core suite.
  494. ```bash
  495. npm run lint
  496. npm run format:check
  497. npm run version:check # package.json vs src/version.ts, server.json, pyproject.toml
  498. ```
  499. ## Releasing
  500. 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.
  501. **Normal flow:** merge conventional commits to `main` → [Release Please](https://github.com/googleapis/release-please) opens a Release PR → merge it → tag is created → CI publishes everywhere.
  502. **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`.
  503. Full checklist, file list, CI secrets, and agent instructions:
  504. - **[`docs/RELEASING.md`](docs/RELEASING.md)** — maintainer release guide
  505. - **[`AGENTS.md`](AGENTS.md)** — quick reference for AI agents
  506. ## Troubleshooting
  507. | Symptom | Likely cause | Fix |
  508. | :---------------------------------------------------------- | :--------------------------------------- | :-------------------------------------------------------------------------------------------------------------- |
  509. | Server exits immediately / `OPENROUTER_API_KEY is required` | Missing or empty API key | Set `OPENROUTER_API_KEY` in client `env` or shell — get one at [openrouter.ai/keys](https://openrouter.ai/keys) |
  510. | `_meta.code: INVALID_CREDENTIALS` or HTTP 401 | Bad or revoked key | Regenerate at [openrouter.ai/keys](https://openrouter.ai/keys); restart the MCP client |
  511. | `_meta.code: MODEL_NOT_FOUND` | Typo or retired model ID | Run `search_models` or `validate_model`; check [openrouter.ai/models](https://openrouter.ai/models) |
  512. | HTTP 402 / insufficient credits | Paid model or generation on zero balance | Add credits at [openrouter.ai/credits](https://openrouter.ai/credits) or use a `:free` model |
  513. | `_meta.code: UPSTREAM_HTTP` with 429 | Rate limit | Wait for `_meta.retry_after_seconds` if present; reduce concurrency |
  514. | `_meta.code: UNSAFE_PATH` | Local path outside sandbox | Put files under `OPENROUTER_INPUT_DIR` or set `OPENROUTER_OUTPUT_DIR` wider; see [Security](#security) |
  515. | `npx` not found (Windows GUI apps) | GUI `PATH` differs from terminal | Use the [Windows npx](#windows-npx) `cmd /c` wrapper |
  516. | No inline image/audio after upgrade | **v4.7.0** with `save_path` set | Expected — result is text + `_meta.save_path` only; omit `save_path` or read the saved file |
  517. | MCP client shows stale tool list | Client cache | Restart MCP / reload window after upgrading the package pin |
  518. Structured errors include `_meta.suggestions` with agent-oriented next steps when available.
  519. ## FAQ
  520. ### Do I need paid OpenRouter credits?
  521. 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.
  522. ### Which MCP clients are supported?
  523. Any MCP-compatible client over stdio: Cursor, Claude Desktop, VS Code Copilot, Windsurf, Cline, Kiro, and custom agents.
  524. ### How is this different from calling OpenRouter directly?
  525. 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.
  526. ### Where is the security advisory for path traversal?
  527. Fixed in 4.5.2+ — see [GHSA-3q7p-736f-x44v](https://github.com/stabgan/openrouter-mcp-multimodal/security/advisories/GHSA-3q7p-736f-x44v), [`SECURITY.md`](./SECURITY.md), and `docs/solutions/security-issues/`.
  528. ## Compatibility
  529. Works with any MCP client. Protocol: **MCP 2025-11-25** (backwards-compatible with 2025-06-18 and earlier). Node **≥ 22** (Docker image uses Node 24).
  530. ## License
  531. Apache 2.0 — see [LICENSE](./LICENSE).
  532. ## Contributing
  533. Issues and PRs welcome. For large changes, open an issue first.
  534. Before submitting: run **`npm run ci`**. Use [Conventional Commits](https://www.conventionalcommits.org/) (`fix:`, `feat:`, etc.) so [Release Please](docs/RELEASING.md) can cut the next release. See **[`docs/RELEASING.md`](docs/RELEASING.md)** if you need to ship a version.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.