Openrouter MCP Multimodal

OpenRouter MCP Multimodal Server

The only MCP server that does text + image + audio + video analysis AND generation in one package. Connect Claude Desktop, Cursor, Kiro, VS Code, Windsurf, or Cline to 300+ LLMs via OpenRouter.

Install · Tools · Examples · Config · Changelog

______________________________________________________________________

安装

npx -y @stabgan/openrouter-mcp-multimodal  # that's it — needs OPENROUTER_API_KEY env var

获取免费的API密钥→ openrouter.ai/keys

一键安装

Kiro Cursor VS Code VS Code Insiders Claude DesktopManual config — Add to claude_desktop_config.json WindsurfManual config — Add to ~/.codeium/windsurf/mcp_config.json ClineManual config — Add via Cline MCP settings Smitherynpx -y @smithery/cli install @stabgan/openrouter-mcp-multimodal --client claude

点击后，目标客户端会打开一个确认提示。粘贴您的 OPENROUTER_API_KEY --deeplink提供了一个占位符，因此共享链接中不会出现任何秘密。

手动设定

npx (recommended)

{
  "mcpServers": {
    "openrouter": {
      "command": "npx",
      "args": ["-y", "@stabgan/openrouter-mcp-multimodal"],
      "env": {
        "OPENROUTER_API_KEY": "sk-or-v1-..."
      }
    }
  }
}

Docker

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

Global install

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

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

为什么是这个？

工具

所有错误都带有 _meta.code 从封闭的分类学来看： INVALID_INPUT · UNSAFE_PATH · UPSTREAM_HTTP · UPSTREAM_TIMEOUT · UPSTREAM_REFUSED · UNSUPPORTED_FORMAT · RESOURCE_TOO_LARGE · ZDR_INCOMPATIBLE · MODEL_NOT_FOUND · JOB_FAILED · JOB_STILL_RUNNING · INTERNAL

用法示例

与提供商路由聊天：

{
  "tool": "chat_completion",
  "arguments": {
    "model": "anthropic/claude-sonnet-4",
    "messages": [{ "role": "user", "content": "Summarize this document" }],
    "provider": { "sort": "price", "ignore": ["openai"], "data_collection": "deny" }
  }
}

从Claude Desktop生成视频：

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

分析图像：

{
  "tool": "analyze_image",
  "arguments": {
    "image": "/path/to/photo.jpg",
    "prompt": "Describe what you see in detail"
  }
}

使用缓存+推理进行聊天（v4.5）：

{
  "tool": "chat_completion",
  "arguments": {
    "model": "deepseek/deepseek-r1",
    "messages": [{ "role": "user", "content": "Prove sqrt(2) is irrational" }],
    "cache": true,
    "include_reasoning": true
  }
}

网络搜索：

{
  "tool": "chat_completion",
  "arguments": {
    "model": "openai/gpt-4o",
    "messages": [{ "role": "user", "content": "What shipped in OpenRouter last week?" }],
    "online": true
  }
}

重新排列文档：

{
  "tool": "rerank_documents",
  "arguments": {
    "query": "best practices for MCP server auth",
    "documents": ["doc A text...", "doc B text...", "doc C text..."],
    "top_n": 3
  }
}

配置

Environment variables (click to expand)

安全

• SSRF保护 --URL获取块私有/链接本地/保留的IPv4和IPv6目标（环回、映射、兼容、多播、6to4、Teredo、ORCHID）。
• 路径沙盒 — save_path 已解决 OPENROUTER_OUTPUT_DIR；遍历尝试被拒绝。以（权力）否决 OPENROUTER_ALLOW_UNSAFE_PATHS=1.
• 无凭证泄漏 -API密钥从不在日志、响应或错误中回显。审计日志记录了每次付费操作调用。

Architecture

src/
├── index.ts                    # Entry, env validation, graceful shutdown
├── tool-handlers.ts            # 14 tools (annotated) + dispatch
├── model-cache.ts              # TTL + in-flight coalescing
├── openrouter-api.ts           # REST client (chat + /videos)
├── errors.ts                   # Closed ErrorCode enum
├── logger.ts                   # JSON-line structured logger
└── tool-handlers/
    ├── fetch-utils.ts          # SSRF, bounded fetch, data-URL parser
    ├── openrouter-errors.ts    # SDK/HTTP → ErrorCode classifier
    ├── completion-utils.ts     # Reasoning-model cutoff detection
    ├── path-safety.ts          # save_path sandbox
    ├── chat-completion.ts      # Text + multimodal chat
    ├── analyze-image.ts        # Vision analysis
    ├── analyze-audio.ts        # Audio transcription
    ├── analyze-video.ts        # Video understanding
    ├── generate-image.ts       # Image generation
    ├── generate-audio.ts       # Audio generation + streaming
    ├── generate-video.ts       # Video generation (async)
    ├── image-utils.ts          # Sharp optimization, MIME sniffing
    ├── audio-utils.ts          # Audio format detection
    ├── video-utils.ts          # Video format detection
    ├── search-models.ts        # Model search
    ├── get-model-info.ts       # Model detail lookup
    └── validate-model.ts       # Model existence check

Design Principles & Research

v4.5的设计借鉴了MCP的最佳实践和学术研究：

• 结果，而非行动 --工具封装了整个工作流（fetch→ 验证→ 调用→ 保存），而不是公开原始API基元。跟随 Phil Schmid的MCP制作指南.
• 平淡无奇的论点 --带有枚举的顶级图元可以降低工具调用失败率。由...支持 傅等（2025） 显示成功随着模式复杂性的增加而下降。
• 故障模式文档 --每个工具描述都包括“失败时间：”和“使用：”部分，提高了选择精度 斯拉普巴赫 （2026）.
• 不受信任的内容标记 --分析工具标记输出 _meta.content_is_untrusted: true 减轻间接快速注射(赵等人，《护爪》).
• 带有重试提示的结构化错误 --关闭 _meta.code 分类学+ retry_after_seconds 击败原始错误字符串。每 Apigene的12条规则.
• MCP 2025-06-18合规性 --结构化产出(outputSchema)、进度通知、工具注释(readOnlyHint, destructiveHint, idempotentHint, openWorldHint).

OpenRouter平台功能浮出水面： 响应缓存 · 网络搜索 · 推理令牌 · 汽车精确 · 重新排序 · 快速缓存

从v2升级

v3+是 添加剂 --没有删除任何工具模式或环境变量。

• 新工具： analyze_video, generate_video, generate_video_from_image, get_video_status, rerank_documents, health_check
• 结构化的 _meta.code 在每个错误响应上
• save_path 默认情况下沙盒--set OPENROUTER_OUTPUT_DIR 或 OPENROUTER_ALLOW_UNSAFE_PATHS=1

发展

git clone https://github.com/stabgan/openrouter-mcp-multimodal.git
cd openrouter-mcp-multimodal
npm install && cp .env.example .env  # Add your API key
npm run build && npm start

npm test                    # 288 unit tests, <1s
npm run test:integration    # Live API tests (16 scenarios)
npm run lint
node scripts/live-e2e.mjs  # 16 live E2E scenarios

兼容性

许可证

Apache 2.0——请参阅 许可证.

贡献

欢迎发布问题和PR。请先打开一个问题以了解重大更改。