OpenRouter MCP Multimodal Server

OpenRouter MCP 多模态

面向多模态 AI Agent 的 MCP 服务。
一次安装 · 21 个工具 · 300 多个 OpenRouter 模型 · 文本、视觉、音频和视频的分析与生成。

快速开始 · 工具 · 示例 · 安全 · 故障排除 · 开发 · 发布 · 常见问题

这是什么？

OpenRouter MCP Multimodal 是一款生产级的 Model Context Protocol（MCP） 服务，已列入官方 MCP 注册表，标识为 io.github.stabgan/openrouter-multimodal。它通过 stdio 将 AI 编码 Agent（Cursor、Claude Desktop、VS Code、Windsurf、Cline 等）连接到 OpenRouter 统一的大模型 API。

与仅支持文本的 MCP 服务不同，只需安装一次，即可覆盖完整的多模态功能：

生产环境加固： 输入/输出路径沙箱（从 v4.5.2 开始也涵盖 analyze_* 本地文件）、SSRF 防护、包含 _meta.code 的结构化错误、MCP 2025-11-25 结构化输出 + 工具图标、异步视频进度通知，以及 3929 项自动化测试（3905 项单元/模拟测试 + 7 项回归测试 + 17 项实时集成测试）。

快速开始

1. 获取 API 密钥（免费套餐即可）→ openrouter.ai/keys

2. 运行服务

export OPENROUTER_API_KEY=sk-or-v1-...
npx -y @stabgan/openrouter-mcp-multimodal

3. 添加到 MCP 客户端 — 从 安装 复制一个 JSON 配置块到客户端配置中：

使用下方手动配置中的 mcpServers 对象。

开始使用无需积分。 google/gemma-4-26b-a4b-it:free 等免费模型可用于聊天和视觉任务。视频／音频生成通常需要积分。

安装

MCP 服务通过多种打包方式分发。此服务使用 Node.js/TypeScript 实现；下表列出了各生态系统的安装方式，以及在此处的运行方式。

uvx 与 npx： 在 MCP 生态中，npx 运行 npm（Node）包，而 uvx 运行 PyPI（Python）包。由于此服务基于 Node，uvx 会使用一个精简的 Python 启动器，该启动器会执行 npx -y @stabgan/openrouter-mcp-multimodal——你仍然需要安装 Node。

一键安装

Cursor
VS Code
Kiro
Claude Desktop / Windsurf / Cline	手动配置 JSON（从下方选择任意一种方法）
Smithery	npx -y @smithery/cli install @stabgan/openrouter-mcp-multimodal --client claude
MCP Registry	官方注册表页面 — npm 和 OCI 包

出现提示时，请粘贴你的 OPENROUTER_API_KEY——深层链接使用占位符，因此密钥不会出现在 URL 中。

手动配置

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

export OPENROUTER_API_KEY=sk-or-v1-...
uvx mcp-server-openrouter-multimodal
# pin npm version: OPENROUTER_MCP_NPM_VERSION=5.1.3 uvx mcp-server-openrouter-multimodal

{
  "mcpServers": {
    "openrouter": {
      "command": "uvx",
      "args": ["mcp-server-openrouter-multimodal"],
      "env": {
        "OPENROUTER_API_KEY": "sk-or-v1-..."
      }
    }
  }
}

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

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

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

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

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

npx -y @smithery/cli install @stabgan/openrouter-mcp-multimodal --client claude
# or: --client cursor | vscode | windsurf | ...

claude mcp add openrouter -- npx -y @stabgan/openrouter-mcp-multimodal
# project scope:
claude mcp add --scope project openrouter -- npx -y @stabgan/openrouter-mcp-multimodal

export OPENROUTER_API_KEY=sk-or-v1-...
npx -y @modelcontextprotocol/inspector npx -y @stabgan/openrouter-mcp-multimodal

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

为什么选择此服务？

工具

共 21 个 MCP 工具。每个工具的描述都包含适用场景、良好 / 不良示例、失败条件和适用范围，帮助 Agent 选对工具并从错误中恢复。

每个错误都包含来自封闭分类体系（13 个代码）的 _meta.code。可根据这些代码进行分支处理，实现程序化处理：

错误信息中会包含 _meta.suggestions，在可用时提供面向 Agent 的后续操作建议。

二进制工具结果（v4.7.0+）

生成工具（generate_image、generate_image_dedicated、generate_audio、text_to_speech、generate_video、generate_video_from_image、get_video_status）会返回图像、音频或视频字节。从 4.7.0 起，行为明确如下：

默认内联上限（可按类型或全局覆盖）：

如果你之前依赖同一工具结果中同时包含已保存文件和内联媒体，请从 _meta.save_path 读取文件（或省略 save_path，以便在低于上限时获取内联媒体）。

示例

聊天（免费模型）

{
  "tool": "chat_completion",
  "arguments": {
    "model": "google/gemma-4-26b-a4b-it:free",
    "messages": [{ "role": "user", "content": "Summarize MCP in one sentence." }]
  }
}

带结构化输出的聊天（JSON Schema）

{
  "tool": "chat_completion",
  "arguments": {
    "model": "openai/gpt-4o",
    "messages": [{ "role": "user", "content": "Extract the name and age from: 'Alice is 30 years old.'" }],
    "response_format": {
      "type": "json_schema",
      "json_schema": {
        "name": "person",
        "schema": {
          "type": "object",
          "properties": {
            "name": { "type": "string" },
            "age": { "type": "integer" }
          },
          "required": ["name", "age"]
        }
      }
    }
  }
}

如需不使用架构的简单 JSON，请使用 "response_format": { "type": "json_object" }。添加 "response_healing": true 可自动修复格式错误的 JSON。

分析图像

{
  "tool": "analyze_image",
  "arguments": {
    "image_path": "diagram.png",
    "question": "List every label in this diagram."
  }
}

使用 image_path 和 question，而不是 image / prompt。

搜索模型（视觉 + 免费）

{
  "tool": "search_models",
  "arguments": {
    "query": "gemma",
    "capabilities": { "vision": true },
    "limit": 10,
    "offset": 0
  }
}

生成视频（异步）

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

如果 max_wait_ms 到期时任务仍在运行，响应会成功返回 _meta.code: JOB_STILL_RUNNING 和一个 video_id — 调用 get_video_status 即可继续。这不是错误。

设置了 save_path 时（如上所示），任务完成后结果会是指向已保存文件的文本指针，而不是内联视频。请参阅二进制工具结果。

嵌入文本（向量嵌入）

{
  "tool": "embed_text",
  "arguments": {
    "texts": ["What is MCP?", "Model Context Protocol enables tool use for LLMs."],
    "model": "openai/text-embedding-3-small",
    "dimensions": 1024
  }
}

返回用于 RAG、语义搜索或聚类的嵌入数组。支持 37+ 个模型 — 传入单个字符串或最多包含 2048 条文本的数组。

结构化决策（System One）

{
  "tool": "decide",
  "arguments": {
    "questions": {
      "is_bug": {
        "type": "noul",
        "instructions": "Is this a bug report or a feature request?",
        "criteria": {
          "true": "Describes broken or incorrect behavior",
          "false": "Requests new functionality"
        }
      }
    },
    "state": {
      "ticket": "The login button does not respond when clicked on Safari."
    }
  }
}

返回校准后的概率，而不是生成的文本。包含三种问题类型：noul（是/否）、choice（选择一个类别）、score（序数评分标准）。模型：typesafe/jev-1.13（默认）、upstage/solar-decide、microsoft/decision-1。

更多示例：docs/plans/tool-description-improvement.md

安全

• 输入路径沙箱 — analyze_* 中的本地路径和参考图像必须位于 OPENROUTER_INPUT_DIR 内（未设置时回退到 OPENROUTER_OUTPUT_DIR，再回退到 cwd）
• 输出路径沙箱 — save_path 必须位于 OPENROUTER_OUTPUT_DIR 内
• 异步任务读取 — get_chat_completion_status 仅解析 OPENROUTER_OUTPUT_DIR/openrouter-jobs/ 下的磁盘路径（4.7.0+）
• SSRF 防护 — 获取 URL 时会阻止私有 IP 和保留 IP
• 不可信内容 — 分析输出会标记 _meta.content_is_untrusted: true
• 原型污染防御 — 所有 API 输出边界（模型记录、嵌入、决策、重排结果、日志上下文）都会递归移除 __proto__、constructor 和 prototype 键，然后再转发给 MCP 客户端
• 密钥脱敏 — stderr JSON 日志记录器会对 API 密钥和敏感值进行脱敏；stdout 专用于 MCP 协议流量

仅在 OPENROUTER_ALLOW_UNSAFE_PATHS=1 时覆盖沙箱（不建议）。

报告漏洞：SECURITY.md（私下披露 — 请勿公开提交漏洞利用相关的问题）。

配置

开发

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

测试

**适用于 CI / 零额度账户的免费模型：**集成测试默认使用 google/gemma-4-26b-a4b-it:free（可通过 OPENROUTER_INTEGRATION_MODEL 覆盖）。GitHub Actions 需要 OPENROUTER_API_KEY 仓库密钥。

模拟测试位于 src/__tests__/mock/ 下，涵盖处理程序、路径沙箱、SSRF 阻止、模型缓存分页、工具描述和结构化输出 — 在核心测试套件之外还增加了 396 个用例。

npm run lint
npm run format:check
npm run version:check   # package.json vs src/version.ts, server.json, pyproject.toml

发布

已发布的制品（npm、PyPI/uvx、Docker、GHCR）均使用 git 标签（vX.Y.Z）中的同一 semver 版本。向 main 推送会运行测试，但不会发布到 npm 或 PyPI。

**常规流程：**将符合 Conventional Commits 规范的提交合并到 main → Release Please 创建 Release PR → 合并该 PR → 创建标签 → CI 发布到所有平台。

**手动流程：**更新所有版本文件 → npm run version:check → npm run ci + 冒烟测试 → 提交 → git tag vX.Y.Z → git push origin vX.Y.Z。

完整清单、文件列表、CI 密钥和 Agent 说明：

• docs/RELEASING.md — 维护者发布指南
• AGENTS.md — AI Agent 快速参考

故障排除

结构化错误在适用时会包含 _meta.suggestions，提供面向 Agent 的后续操作建议。

常见问题

我需要购买 OpenRouter 额度吗？

开始使用不需要。免费模型可用于聊天和视觉任务。音频/视频生成通常需要额度；部分模型的分析可能返回 402 — 服务会将其作为结构化错误呈现。

支持哪些 MCP 客户端？

任何通过 stdio 连接的兼容 MCP 客户端：Cursor、Claude Desktop、VS Code Copilot、Windsurf、Cline、Kiro 和自定义 Agent。

这与直接调用 OpenRouter 有何不同？

此服务添加了 MCP 工具架构、安全沙箱、错误分类、模型缓存、带进度通知的异步视频轮询，以及面向 Agent 的工具描述，因此大模型无需编写自定义 HTTP 代码，就能调用正确的功能。

路径遍历的安全公告在哪里？

已在 4.5.2+ 中修复——请参阅 GHSA-3q7p-736f-x44v、SECURITY.md 和 docs/solutions/security-issues/。

兼容性

适用于任何 MCP 客户端。协议：MCP 2025-11-25（向后兼容 2025-06-18 及更早版本）。Node ≥ 22（Docker 镜像使用 Node 24）。

许可证

Apache 2.0——请参阅 LICENSE。

贡献

欢迎提交 Issue 和 PR。对于较大的更改，请先创建 Issue。

提交前：运行 npm run ci。请使用 Conventional Commits（fix:、feat: 等），以便 Release Please 创建下一个版本。如果需要发布版本，请参阅 docs/RELEASING.md。