MCP Vision Relay

MCP Vision Relay

MCP Vision Relay 是一个 MCP 服务器，通过封装本地安装的 Gemini 和 Qwen 命令行工具，为 Claude、Codex 等仅支持文本的 MCP 客户端提供图像分析能力，使其能够处理本地路径、URL 或 base64 编码的图片。

人工智能聊天机器人开发者工具 #图像分析 #多模态中继 #MCP 服务器 #命令行集成 .TypeScript

评分 : 2.5分

下载量 : 0

更新时间 : 2025-12-04

打开站点

什么是MCP Vision Relay?

MCP Vision Relay是一个桥梁工具，它允许不支持原生图像分析的AI助手（如Claude、Codex等）通过调用您本地已安装的多模态AI工具来分析图像。它将这些工具封装成标准化的MCP服务器，让您的AI助手能够像使用内置功能一样使用图像分析能力。

如何使用MCP Vision Relay?

使用分为三步：1) 在您的电脑上安装并配置好Gemini CLI或Qwen CLI；2) 安装并运行MCP Vision Relay服务器；3) 在您的AI助手（如Claude Desktop）中注册这个服务器。完成后，您就可以在对话中直接让AI助手分析图片了。

适用场景

当您使用的AI助手（例如通过某些服务商接入的Claude或Codex）本身没有图像分析功能时，这个工具就非常有用。它为您提供了一个低成本、不更换服务商就能恢复多模态能力的解决方案。例如，分析截图中的代码、解释图表内容、描述照片中的场景等。

主要功能

统一的图像分析工具

提供 `gemini_analyze_image` 和 `qwen_analyze_image` 两个工具，支持通过本地文件路径、网络图片链接或Base64编码字符串三种方式输入图片进行分析。

多提供商中继架构

通过抽象的“提供商”层，可以轻松切换或扩展不同的命令行工具（CLI）。保留了对模型选择、输出格式等核心配置的控制能力。

健壮的输入处理

自动检查图片大小和文件格式，必要时会自动下载网络图片或解码Base64数据到临时文件，并在使用后清理，确保安全性和资源管理。

高度可配置的执行

支持沙盒模式、超时设置、附加命令行参数、覆盖默认模型等。可以通过环境变量或`.env`文件进行灵活配置。

结构化的可操作输出

对底层CLI的输出进行整理，并附加元数据（如使用的模型、分析耗时、图片来源等），方便AI助手在界面中展示或进行后续处理。

优势

低成本扩展能力：无需升级到更昂贵的支持视觉的AI服务套餐，利用本地免费或低成本的CLI工具即可。

无缝集成：在支持的AI助手（如Claude Desktop）中注册后，图像分析工具就像原生功能一样出现在工具列表中。

灵活选择：支持多个后端（Gemini, Qwen），您可以根据需求、模型性能或成本选择最合适的一个。

隐私可控：图片分析过程发生在您本地调用的CLI上，您可以了解数据是如何被发送到对应服务商的。

局限性

依赖本地环境：需要在您的电脑上预先安装并正确配置好对应的CLI工具，并完成登录认证。

额外步骤：相比AI助手内置的视觉功能，需要额外的安装和配置步骤。

性能依赖：分析速度和效果取决于您选择的CLI工具及其背后的AI模型。

间接调用：并非AI助手原生理解图像，而是将任务“转交”给另一个工具，可能在某些复杂交互场景下不如原生集成流畅。

如何使用

环境准备

确保您的电脑已安装 Node.js (版本18或更高)。然后，根据您的选择，安装并配置好 Google Gemini CLI 或 Qwen CLI。请确保在命令行中直接运行 `gemini -p "hi"` 或 `qwen -p "hi"` 能正常返回结果，这表示CLI已正确安装和授权。

安装与构建 MCP Vision Relay

下载或克隆MCP Vision Relay项目，进入项目目录，安装依赖并构建项目。

配置（可选）

复制项目中的 `.env.example` 文件为 `.env`，并根据您的需要修改配置，例如设置默认模型、超时时间等。如果您保持CLI的默认安装和配置，此步骤可以跳过。

在AI助手中注册服务器

在您使用的AI助手（如Claude Desktop或Codex CLI）中，将MCP Vision Relay添加为一个MCP服务器。注意：注册命令需要直接调用入口文件，而不是通过npm脚本，以避免额外输出干扰通信。

开始使用

注册成功后，在AI助手的对话界面中，您应该能看到新添加的图像分析工具（如 `gemini_analyze_image`）。您就可以在对话中要求AI助手使用这些工具来分析图片了。

使用案例

分析技术图表

您截取了一张系统架构图，想让AI助手解释其中的组件和工作流程。

解释错误截图

程序运行时弹出了一个错误对话框，您截图后想了解这个错误的具体含义和可能的原因。

描述照片内容

您有一张旅行时拍摄的风景照，想让AI助手生成一段优美的描述文字。

常见问题

我已经有能分析图像的AI了，为什么还需要这个工具？

安装时遇到“命令未找到”错误怎么办？

在Claude Desktop中添加服务器失败，提示握手错误？

工具调用成功了，但返回“图片太大”或“格式不支持”的错误？

支持除了Gemini和Qwen之外的其他模型吗？

🚀 MCP Vision Relay

MCP Vision Relay 将本地安装的多模态 CLI（目前支持 Google Gemini CLI 与 Qwen CLI）封装为 Model Context Protocol (MCP) 服务器，帮助 Claude、Codex 等支持 MCP 的工具直接使用它们的看图能力。通过将调用请求通过 Gemini/Qwen CLI 进行中转，MCP Vision Relay 为那些部署提供了一条经济实惠的途径，使其在那些目前，当 Claude Code 连接到 k2、DeepSeek 或 MiniMax M2 等提供商时，背后的模型仅支持文本，没有内置的视觉能力。通过 MCP Vision Relay，这些部署无需更换提供商即可重新获得多模态功能。

English | 中文说明

✨ 主要特性

统一图像工具 – gemini_analyze_image 和 qwen_analyze_image 两个工具覆盖路径、URL、base64 三种输入。
提供商中继架构 – 通过 provider 抽象切换或扩展不同 CLI，保留模型、输出格式等配置能力。
强大的输入处理 – 自动校验图片大小、扩展名，必要时下载或写入临时文件并在使用后清理。
可配置执行 – 支持可选 sandbox、超时、额外旗标、模型覆盖，以及 .env/环境变量配置。
可操作输出 – 对 stdout 进行规整并附加元信息，便于客户端在 UI 中展示或后续处理。

🚀 快速开始

前提条件

Node.js ≥ 18
已安装并能在命令行直接调用的 Gemini CLI 与/或 Qwen CLI
对应 CLI 的登陆/鉴权已完成（确保 gemini -p "hi"、qwen -p "hi" 能返回结果）

安装与构建

npm install
npm run build

运行 MCP 服务器

# 开发模式（tsx 直接启动 TypeScript）
npm run dev

# 生产模式（使用编译产物）
npm run start

服务器通过 stdio 与 MCP 客户端通信，适用于 claude mcp add、codex mcp add 等命令。

💻 使用示例

Claude

claude mcp add mcp-vision-relay -- npx tsx /absolute/path/to/mcp-vision-relay/src/index.ts

Codex CLI

codex mcp add mcp-vision-relay -- node /absolute/path/to/mcp-vision-relay/dist/index.js

完成后即可在会话/任务中选择 mcp-vision-relay 的工具调用。

📚 详细文档

可用工具

`gemini_analyze_image`

分析图像并返回 Gemini CLI 给出的描述。

参数	类型	说明
`image`	string	必填；本地路径、HTTP(S) URL 或 base64 字符串
`prompt`	string?	额外指令，默认使用 `GEMINI_DEFAULT_PROMPT`
`model`	string?	覆盖默认模型（如 `gemini-2.0-flash`）
`outputFormat`	`"text" \| "json"`?	控制 `-o` 输出格式
`sandbox`	boolean?	是否添加 `-s` sandbox 旗标
`extraFlags`	string[]?	附加自定义参数
`timeoutMs`	number?	CLI 超时（默认 120000ms）

返回内容包含一段 Markdown 文本与元信息（模型、输入来源、耗时等）。

`qwen_analyze_image`

走 Qwen CLI 进行图像理解。逻辑与 Gemini 类似，但会在需要时自动把本地文件转成 data URL 供 CLI 读取。

参数	类型	说明
`image`	string	必填；本地路径、HTTP(S) URL 或 base64 字符串
`prompt`	string?	额外指令，默认使用 `QWEN_DEFAULT_PROMPT`
`model`	string?	Qwen 模型（如 `qwen2.5-omni-medium`）
`sandbox`	boolean?	是否加 `-s`
`extraFlags`	string[]?	附加参数
`timeoutMs`	number?	CLI 超时（默认 120000ms）

配置

复制 .env.example 进行配置，常用条目：

GEMINI_CLI_COMMAND / QWEN_CLI_COMMAND：CLI 可执行文件路径。
GEMINI_DEFAULT_MODEL / QWEN_DEFAULT_MODEL：默认模型名。
GEMINI_OUTPUT_FORMAT：控制 Gemini 输出（text 或 json）。
MCP_COMMAND_TIMEOUT_MS：全局超时（毫秒）。
MCP_MAX_IMAGE_BYTES：允许的最大图片大小。
MCP_ALLOWED_IMAGE_EXTENSIONS：允许的扩展名列表。
MCP_IMAGE_TEMP_DIR：存放下载/解码后临时文件的目录。

如需针对单次调用覆盖 CLI 命令，可在工具参数中提供 cliPath（Gemini/Qwen 均支持）。

本地诊断

项目提供两个简单脚本，便于手动验证 CLI 调用：

npx tsx scripts/dev/manual-gemini-test.ts
npx tsx scripts/dev/manual-qwen-test.ts

确保在执行前已完成 npm run build 或使用 ts-node/tsx。

项目结构

src/
  index.ts                 # 程序入口，加载 env 并启动 MCP 服务器
  config/                  # 配置解析（appConfig 等）
  providers/               # CLI provider 适配层（Gemini/Qwen）
  server/                  # MCP server wiring
  tools/                   # MCP 工具定义与注册
  utils/                   # 文件、CLI 调度等公共工具
scripts/
  dev/                     # 手动验证脚本
test-assets/               # 示例图像资源