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/               # 示例圖像資源