![\"OpenRouter](\"assets/logo.png\"){kind=logo}
\n\n \n
\n The MCP server for multimodal AI agents.
\n One install · 19 tools · 300+ OpenRouter models · text, vision, audio & video — analysis and generation.\n
\n ![\"npm](\"https://img.shields.io/npm/v/@stabgan/openrouter-mcp-multimodal.svg?label=npm&color=cb3837&logo=npm\")
\n ![\"PyPI](\"https://img.shields.io/pypi/v/mcp-server-openrouter-multimodal.svg?label=pypi&color=3775A9&logo=pypi&logoColor=white\")
\n ![\"GitHub](\"https://img.shields.io/github/v/release/stabgan/openrouter-mcp-multimodal?label=release&color=6366f1\")
![\"Docker](\"https://img.shields.io/docker/v/stabgan/openrouter-mcp-multimodal/latest?label=docker&color=2496ed&logo=docker&logoColor=white\")
![\"CI](\"https://github.com/stabgan/openrouter-mcp-multimodal/actions/workflows/ci.yml/badge.svg\"){kind=icon}
\n ![\"Apache](\"https://img.shields.io/badge/License-Apache_2.0-blue.svg\"){kind=icon}
\n ![\"Node.js](\"https://img.shields.io/badge/node-%E2%89%A522-43853d?logo=node.js&logoColor=white\"){kind=icon}
\n ![\"npm](\"https://img.shields.io/npm/dt/@stabgan/openrouter-mcp-multimodal.svg?label=npm%20downloads&color=cb3837&logo=npm\")
\n ![\"Docker](\"https://img.shields.io/docker/pulls/stabgan/openrouter-mcp-multimodal.svg?label=docker%20pulls&color=2496ed&logo=docker&logoColor=white\")
\n ![\"MCP](\"https://img.shields.io/badge/MCP_Registry-listed-6366f1\"){kind=icon}
![\"Smithery](\"https://img.shields.io/badge/Smithery-Install-6366f1\"){kind=icon}
\n Quick start ·\n Tools ·\n Examples ·\n Security ·\n Troubleshooting ·\n Development ·\n Releasing ·\n FAQ\n
\n\n---\n\n## What is this?\n\n**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.\n\nUnlike text-only MCP servers, one install covers the **full multimodal surface**:\n\n| Capability | Tools | Highlights |\n| :---------- | :-------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| **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 |\n| **Vision** | `analyze_image`, `generate_image`, `generate_image_dedicated` | OCR, captioning, VQA, image generation with reference inputs, dedicated Image API with resolution/quality/format control |\n| **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) |\n| **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 |\n| **Catalog** | `search_models`, `get_model_info`, `validate_model`, `rerank_documents`, `health_check` | Model discovery, validation, reranking, ops health |\n\n**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).\n\n## Quick start\n\n**1. Get an API key** (free tier works) → [openrouter.ai/keys](https://openrouter.ai/keys)\n\n**2. Run the server**\n\n```bash\nexport OPENROUTER_API_KEY=sk-or-v1-...\nnpx -y @stabgan/openrouter-mcp-multimodal\n```\n\n**3. Add to your MCP client** — copy one JSON block from [Install](#install) into your client config:\n\n| Client | Config location |\n| :----------------- | :-------------------------------------------------------------------------------------------------------------------------------- |\n| **Cursor** | Project: `.cursor/mcp.json` · User: Cursor Settings → MCP |\n| **Claude Desktop** | macOS: `~/Library/Application Support/Claude/claude_desktop_config.json` · Windows: `%APPDATA%\\Claude\\claude_desktop_config.json` |\n| **VS Code** | `.vscode/mcp.json` (workspace) or User Settings → MCP |\n| **Windsurf** | Windsurf Settings → MCP (same `mcpServers` JSON shape as Cursor) |\n\nUse the `mcpServers` object from [Manual config](#manual-config) below.\n\n> **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.\n\n## Install\n\nMCP 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.\n\n| Method | Runtime | Best for | This server |\n| :-------------------------------------- | :------------------------------- | :------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------- |\n| **[npx](#manual-config)** | Node.js 22+ | Most MCP clients (default) | ✅ `@stabgan/openrouter-mcp-multimodal` |\n| **[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/) |\n| **[npm global](#manual-config)** | Node.js 22+ | Pin a version without re-downloading | ✅ |\n| **[node (local)](#manual-config)** | Node.js 22+ | Contributors / air-gapped builds | ✅ |\n| **[Docker Hub](#manual-config)** | Docker | Isolation, no Node on host | ✅ `stabgan/openrouter-mcp-multimodal` |\n| **[GHCR](#manual-config)** | Docker | GitHub-native OCI pulls | ✅ `ghcr.io/stabgan/openrouter-mcp-multimodal` |\n| **[Smithery CLI](#smithery)** | Node.js (via installer) | Interactive install into Claude/Cursor/etc. | ✅ |\n| **[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) |\n| **[One-click deeplinks](#one-click)** | Node.js | Cursor, VS Code, Kiro | ✅ |\n| **[Claude Code CLI](#claude-code-cli)** | Node.js | Terminal-first Claude Code users | ✅ |\n| **[MCP Inspector](#mcp-inspector)** | Node.js | Debug / list tools locally | ✅ |\n| **Windows `cmd /c npx`** | Node.js | Claude Desktop / Cursor when `npx` not on GUI PATH | ✅ [see below](#windows-npx) |\n| pip / uv (direct) | — | Native Python MCP servers only | — use **uvx** row above |\n| DXT desktop extensions | — | Bundled Claude Desktop `.dxt` | not yet |\n| Remote HTTP / SSE | — | Hosted Smithery / Cloudflare endpoints | via [Smithery](https://smithery.ai/server/@stabgan/openrouter-mcp-multimodal) |\n\n> **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.\n\n### One-click\n\n| Cursor | ![\"Add](\"https://cursor.com/deeplink/mcp-install-dark.svg\") |
| VS Code | ![\"Add](\"https://img.shields.io/badge/Add_to-VS_Code-007ACC?style=for-the-badge&logo=visualstudiocode&logoColor=white\"){kind=icon} |
| Kiro | ![\"Add](\"https://img.shields.io/badge/Add_to-Kiro-232F3E?style=for-the-badge&logo=amazonaws&logoColor=white\"){kind=icon} |
| Claude Desktop / Windsurf / Cline | Manual JSON config (pick any method below) |
| Smithery | npx -y @smithery/cli install @stabgan/openrouter-mcp-multimodal --client claude |
| MCP Registry | Official registry page — npm + OCI packages |