MCP Vision Relay

English | 中文说明

MCP Vision Relay 将本地安装的多模态 CLI（目前支持 Google Gemini CLI 与 Qwen CLI）封装为 Model Context Protocol (MCP) 服务器，帮助 Claude、Codex 等支持 MCP 的工具直接使用它们的看图能力。

Why it matters: when Claude Code connects to providers such as k2, DeepSeek, or MiniMax M2, the backing models today are text-only—no built-in vision. By relaying calls through Gemini/Qwen CLI, MCP Vision Relay gives those deployments an inexpensive path to regain multimodal features without switching providers.

Features

• Unified image tools – gemini_analyze_image 与 qwen_analyze_image 两个工具覆盖路径、URL、base64 三种输入。

• Provider relay architecture – 通过 provider 抽象切换或扩展不同 CLI，保留模型、输出格式等配置能力。

• Robust input handling – 自动校验图片大小、扩展名，必要时下载或写入临时文件并在使用后清理。

• Configurable execution – 支持可选 sandbox、超时、额外旗标、模型覆盖，以及 .env/环境变量配置。

• Actionable outputs – 对 stdout 进行规整并附加元信息，便于客户端在 UI 中展示或后续处理。

Quick Start

Prerequisites

1. Node.js ≥ 18

2. 已安装并能在命令行直接调用的 Gemini CLI 与/或 Qwen CLI

3. 对应 CLI 的登陆/鉴权已完成（确保 gemini -p "hi"、qwen -p "hi" 能返回结果）

Install & Build

npm install
npm run build

Run the MCP server

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

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

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

MCP Integration Examples

⚠️ When registering the server with an MCP client, invoke the entry point directly. Running npm run dev inside the registration command causes npm to print a banner on stdout, which breaks the MCP handshake. If you must keep the npm script, wrap it with npm --silent run dev -- so no extra text reaches stdout.

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 的工具调用。

Available Tools

gemini_analyze_image

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

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

qwen_analyze_image

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

Configuration

复制 .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 均支持）。

Local Diagnostics

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

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

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

Project Structure

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

Roadmap

• ✅ Gemini CLI 图像分析

• ✅ Qwen CLI 图像分析（含自动 data URL）

• ⏳ 资源列表与更多多模态 provider

• ⏳ 自动化测试与 lint/format pipeline

License

MIT License. 欢迎 issue / PR 贡献改进。

Acknowledgements

• Model Context Protocol

• Google Gemini CLI

• @qwen-code/qwen-code