Vision-Bridge MCP Server 🧿

English | 中文

给不支持多模态的模型（如 DeepSeek、纯文本模型）加一双"眼睛"：通过 MCP 暴露 看图 / OCR 工具，底层调用任意 OpenAI 兼容 的视觉大模型（智谱、千问、OpenAI 等），把图片理解成文字返回给 AI。

你的模型（无视觉）--调用MCP工具--> Vision-Bridge Server --图片--> 视觉大模型
                                          ^ 理解图片          |
用户发图片给你 <--返回文字描述<-----------┘<------------------┘

✨ 特性

通用 OpenAI 兼容：一套代码，可切换智谱 / 千问 / OpenAI / 任何兼容端点，只改配置不改代码
两个工具：look_at_image（看图理解）+ extract_text_from_image（OCR 逐字转录）
图片预处理：自动修正方向、压缩限长、转 JPEG，大图不糊细节
深度思考：智谱模型默认开启 thinking 模式，精度优先
限流重试：429 自动指数退避重试，API 错误原样透传
零成本可选：智谱 glm-4.6v-flash 或千问新用户 100 万 token 均可免费使用
一键安装：pip install 直装，装完即可用 vision-bridge 命令

🚀 快速开始

方式一：pip 一键安装（推荐）

pip install "vision-bridge-mcp @ git+https://github.com/zgz518/vision-bridge-mcp.git"

然后在你的工作目录创建 .env（见配置），验证：

vision-bridge --test                                # 自检：查看配置和工具
vision-bridge --once /path/to/image.png "有什么"     # 命令行单图联调

方式二：uv

uv tool install git+https://github.com/zgz518/vision-bridge-mcp
vision-bridge --test

方式三：克隆 + 虚拟环境

git clone https://github.com/zgz518/vision-bridge-mcp.git
cd vision-bridge-mcp
python -m venv .venv
# Windows: .venv\Scripts\activate   macOS/Linux: source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
python server.py --test

方式四：直接把链接发给 AI 助手（最省事）

如果你在用 WorkBuddy / Claude Code / Cursor 等 AI 助手，什么都不用自己做——把下面这条消息发给它即可：

帮我安装并使用这个 MCP 服务器：https://github.com/zgz518/vision-bridge-mcp

AI 会自动完成克隆 / 安装依赖 / 生成配置，并引导你提供 API Key（智谱/千问/OpenAI 任选），最后注册到你的 MCP 客户端。你只需要把 Key 交给它。

⚙️ 配置

复制下面的内容，在你的运行目录新建 .env 文件并粘贴（选一家服务商即可，默认智谱免费版）：

# 方式一：智谱（免费，推荐）
# 申请 Key：https://bigmodel.cn 控制台 -> API Keys
VISION_BASE_URL=https://open.bigmodel.cn/api/paas/v4
VISION_API_KEY=你的智谱key
VISION_MODEL=glm-4.6v-flash

# 方式二：阿里云百炼·千问（新用户 100 万 token 免费）
# VISION_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
# VISION_API_KEY=你的百炼key
# VISION_MODEL=qwen-vl-max

# 方式三：OpenAI
# VISION_BASE_URL=https://api.openai.com/v1
# VISION_API_KEY=sk-xxxx
# VISION_MODEL=gpt-4o-mini

服务商速览：

服务商	VISION_BASE_URL	模型示例	费用
智谱（默认）	`https://open.bigmodel.cn/api/paas/v4`	`glm-4.6v-flash`	免费
阿里云百炼·千问	`https://dashscope.aliyuncs.com/compatible-mode/v1`	`qwen-vl-max`	新用户 100 万 token 免费
OpenAI	`https://api.openai.com/v1`	`gpt-4o-mini`	付费

pip/uv 安装时，.env 放在你运行 vision-bridge 命令的目录；clone 时放在项目根目录。项目内也附有 .env.example 模板，clone 用户可直接 cp .env.example .env 使用。

🔌 接入 MCP 客户端

WorkBuddy

编辑 %USERPROFILE%\.workbuddy\mcp.json（不带点前缀），加入：

{
  "mcpServers": {
    "vision-bridge-mcp": {
      "type": "stdio",
      "command": "vision-bridge",
      "args": []
    }
  }
}

（clone 方式则 command 填 .venv/Scripts/python.exe、args 填 server.py 绝对路径）

保存后：连接器管理 → 右上角【自定义连接器】→ 找到 vision-bridge-mcp → 点「信任」启用。

Claude Code / Cline / Cherry Studio 等

以 Claude Code 为例（.mcp.json 或项目配置）：

{
  "mcpServers": {
    "vision-bridge-mcp": {
      "command": "vision-bridge"
    }
  }
}

💡 使用技巧（重要）

纯文本模型（尤其是 DeepSeek 系）有一个通病：上传图片后不主动调工具，反而凭图片路径幻觉出内容。服务器已内置「严禁幻觉」指令，但如果你的模型仍不自动触发，请在客户端的全局指令/人设里加一条常驻规则：

当用户上传或粘贴图片，或消息中出现以 .png/.jpg/.jpeg/.webp/.gif 结尾的本地文件路径时，你必须立即调用 look_at_image 工具，把图片路径作为 image 参数传入。在工具返回结果之前，禁止描述任何图片内容（未调工具就描述 = 幻觉）。用户要求提取图片中的文字时，改调 extract_text_from_image。

或者更简单：每次贴图后附带一句 "看这张图"，即可触发。

🛠 工具说明

工具	参数	用途
`look_at_image`	`image`: 本地路径或 http(s) URL；`prompt`: 可选关注点	看图，返回结构化中文描述
`extract_text_from_image`	`image`: 本地路径或 http(s) URL	OCR，逐字转录图片中的文字

⚠️ 注意事项

密钥安全：.env 已被 gitignore 排除，不要把真实 Key 写进任何会提交的文件；
限流：免费档模型有速率限制（429），已内置重试；高频使用建议充值升级档位或换用付费模型；
精度：免费版为轻量模型，对细节/计数要求高的场景，换旗舰模型（智谱 glm-4.6v、千问 qwen-vl-max）。

📄 License

MIT