mcp-vision

通过 火山引擎方舟 视觉模型（doubao-seed-2.0-pro）为无视觉能力的主模型提供识图能力的 MCP 服务器。

主模型（如 GLM-5.2）调用本 MCP 提供的工具，把图片交给视觉模型，拿到文字描述回填到对话中，从而间接获得「看图」能力。

跨平台支持 macOS / Linux / Windows，配置路径与工具行为一致。

提供的工具

工具	作用
recognize_image	通用识图：描述图片内容（文字/物体/人物/场景/布局/颜色），prompt 可定制
ocr_image	纯文字提取：只返回图片中的文字，保持排版，不描述图像本身

两个工具的 image 参数统一支持三种形式：

1. 本地文件路径：/tmp/screenshot.png、./pic.jpg
2. http(s) URL：https://example.com/a.png
3. base64 字符串：裸串即可，无需 data: 前缀

安装

macOS / Linux

cd mcp-vision
python3 -m venv .venv
.venv/bin/pip install -e .

Windows（PowerShell）

cd C:\Users\<你的用户名>\mcp-vision
python -m venv .venv
.venv\Scripts\pip install -e .

安装后生成两个可执行命令：mcp-vision（MCP 服务器）和 vision-config（可视化配置工具）。 macOS/Linux 位于 .venv/bin/，Windows 位于 .venv\Scripts\（带 .exe 后缀）。

依赖与版本要求

venv 和 pip 都是 Python 标准库自带，无需额外安装任何工具，只要有 Python 即可。项目直接依赖只有 2 个第三方包：

依赖	推荐版本（已验证可用）	最低版本	说明
Python	3.14.6	3.10	venv/pip 自带，无需额外装
mcp	1.28.1	1.2.0	MCP SDK（FastMCP）
httpx	0.28.1	0.27.0	调用视觉模型 HTTP 接口

其余包（anyio、pydantic、uvicorn、starlette 等）均为 mcp 的传递依赖，安装时自动拉取，无需手动指定版本。 配置工具 vision-config 的 Web 服务使用 Python 标准库 http.server，不依赖 Flask 或任何第三方 Web 框架。

配置（统一在 opencode.json 管理）

视觉模型的 model / baseURL / key 全部由 ~/.config/opencode/opencode.json 的 mcp.vision.environment 注入，切换平台时只改这一个文件，无需建 .env、无需动代码。

环境变量	含义	必填
ARK_API_KEY	视觉模型凭据	是
ARK_BASE_URL	OpenAI 兼容接入点（/chat/completions）	是
VISION_MODEL	视觉模型 id	是
VISION_MAX_TOKENS	单次识别最大输出 token（默认 2048）	否
VISION_TIMEOUT	请求超时秒数（默认 60）	否

接入 opencode

在 ~/.config/opencode/opencode.json 顶层增加 mcp 字段（三个核心变量都在 environment 里）：

{
  "mcp": {
    "vision": {
      "type": "local",
      "command": ["/<你的路径>/mcp-vision/.venv/bin/mcp-vision"],
      "enabled": true,
      "environment": {
        "ARK_API_KEY": "ark-你的key",
        "ARK_BASE_URL": "https://ark.cn-beijing.volces.com/api/plan/v3",
        "VISION_MODEL": "doubao-seed-2.0-pro"
      }
    }
  }
}

切换平台示例

只改 environment 三个值，重启 opencode 生效：

// 换到 OpenAI 官方
"environment": {
  "ARK_API_KEY": "sk-你的openai-key",
  "ARK_BASE_URL": "https://api.openai.com/v1",
  "VISION_MODEL": "gpt-4o"
}

// 换到阿里通义千问 VL
"environment": {
  "ARK_API_KEY": "sk-你的dashscope-key",
  "ARK_BASE_URL": "https://dashscope.aliyuncs.com/compatible-mode/v1",
  "VISION_MODEL": "qwen-vl-max"
}

前提：目标接口需兼容 OpenAI /chat/completions + image_url 格式。

Windows 上的 command 路径

Windows 的 venv 可执行文件在 Scripts 目录且带 .exe 后缀。JSON 中的路径可用正斜杠 /（推荐，免转义）或双反斜杠 \\：

// 写法一：正斜杠（推荐，无需转义）
"command": ["C:/Users/<你的用户名>/mcp-vision/.venv/Scripts/mcp-vision.exe"]

// 写法二：双反斜杠
"command": ["C:\\Users\\<你的用户名>\\mcp-vision\\.venv\\Scripts\\mcp-vision.exe"]

opencode 全平台统一使用 ~/.config/opencode/opencode.json 作为全局配置。 Windows 上即 C:\Users\<用户名>\.config\opencode\opencode.json，与 macOS/Linux 路径结构一致，无需额外设置。

若未 pip install -e .，也可直接用 python 运行：

"command": ["python3", "-m", "mcp_vision.server"]

（需把 src 加入 PYTHONPATH，或在项目目录下运行）

接入后，主模型即可在需要看图时自动调用 recognize_image / ocr_image。

可视化配置工具（vision-config）

配套的本地 Web 工具，浏览器里编辑三个变量、一键切预设平台、测试连接、保存写回 opencode.json（带备份）。

macOS / Linux

.venv/bin/vision-config                  # 默认 http://127.0.0.1:7788，自动开浏览器
PORT=8000 .venv/bin/vision-config        # 换端口

Windows（PowerShell）

.venv\Scripts\vision-config.exe                      # 默认 http://127.0.0.1:7788，自动开浏览器
$env:PORT=8000; .venv\Scripts\vision-config.exe      # 换端口

功能：

• 预设平台一键填充：火山引擎 / OpenAI / 通义千问 / 智谱 GLM-4V / 自定义
• 测试连接：用当前填的 model+baseURL+key 发一张测试图，验证视觉接口可用并返回识别结果
• 保存写回：写入 opencode.json 的 mcp.vision.environment，保存前自动备份为 opencode.json.vision-bak-时间戳
• key 安全：脱敏显示，未改动则保留原值，不会被脱敏串覆盖
• 只绑 127.0.0.1：不暴露外网

保存后需重启 opencode 让 MCP 子进程读到新配置。

命令行自测

# 单独跑 stdio server（会阻塞等待 MCP 客户端握手）
mcp-vision

开发

python -c "import mcp_vision.server"   # 导入自检
python -m py_compile src/mcp_vision/server.py