MCP Vision Relay enables text-only AI models to analyze images by relaying requests through locally-installed multimodal CLIs (Google Gemini and Qwen) via the Model Context Protocol.
Image Analysis Tools
gemini_analyze_imageandqwen_analyze_imagetools for processing images using Gemini or Qwen's vision capabilitiesSupport for local file paths, HTTP(S) URLs, and base64-encoded images with automatic validation and temporary file management
Customizable Execution
Custom prompts and model overrides (e.g.,
gemini-2.0-flash,qwen2.5-omni-medium)Output format control (text or JSON for Gemini)
Configurable timeouts (up to 600 seconds), sandbox mode, and custom CLI flags
Per-call CLI path overriding via
cliPathparameter
Integration & Output
Seamless MCP integration for clients like Claude and Codex to gain multimodal capabilities
Structured responses with Markdown content and metadata (model used, processing time, input source)
Environment configuration support via .env files for CLI paths and default settings
Use Case: Bridge text-only AI deployments (like Claude with DeepSeek, MiniMax, or k2 providers) to gain vision capabilities without switching providers.
Provides image analysis capabilities by relaying requests to the Google Gemini CLI, supporting local paths, URLs, and base64 image inputs with configurable models, prompts, and output formats.
MCP Vision Relay
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
Node.js ≥ 18
已安装并能在命令行直接调用的 Gemini CLI 与/或 Qwen CLI
对应 CLI 的登陆/鉴权已完成（确保
gemini -p "hi"、qwen -p "hi"能返回结果）
Install & Build
Run the MCP server
服务器通过 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 devinside 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 withnpm --silent run dev --so no extra text reaches stdout.
Claude
Codex CLI
完成后即可在会话/任务中选择 mcp-vision-relay 的工具调用。
Available Tools
gemini_analyze_image
分析图像并返回 Gemini CLI 给出的描述。
参数 | 类型 | 说明 |
| string | 必填；本地路径、HTTP(S) URL 或 base64 字符串 |
| string? | 额外指令，默认使用
|
| string? | 覆盖默认模型（如
） |
|
? | 控制
输出格式 |
| boolean? | 是否添加
sandbox 旗标 |
| string[]? | 附加自定义参数 |
| number? | CLI 超时（默认 120000ms） |
返回内容包含一段 Markdown 文本与元信息（模型、输入来源、耗时等）。
qwen_analyze_image
走 Qwen CLI 进行图像理解。逻辑与 Gemini 类似，但会在需要时自动把本地文件转成 data URL 供 CLI 读取。
参数 | 类型 | 说明 |
| string | 必填；本地路径、HTTP(S) URL 或 base64 字符串 |
| string? | 额外指令，默认使用
|
| string? | Qwen 模型（如
） |
| boolean? | 是否加
|
| string[]? | 附加参数 |
| number? | CLI 超时（默认 120000ms） |
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 调用：
确保在执行前已完成 npm run build 或使用 ts-node/tsx。
Project Structure
Roadmap
✅ Gemini CLI 图像分析
✅ Qwen CLI 图像分析（含自动 data URL）
⏳ 资源列表与更多多模态 provider
⏳ 自动化测试与 lint/format pipeline
License
MIT License. 欢迎 issue / PR 贡献改进。