vision-mcp

图像理解 MCP Server(stdio 形式),对标 z.ai vision-mcp-server,底层经 OpenAI 兼容接口调用视觉模型(支持火山方舟 ARK 等 provider,默认 doubao-seed-2.0-code)。

工具一览

共 7 个图像工具(未实现 video_analysis):

工具	说明
image_analysis	通用图像理解
extract_text_from_screenshot	截图 OCR,提取代码/终端/文档/普通文本
diagnose_error_screenshot	分析错误截图,给可操作修复建议
understand_technical_diagram	解读架构图/流程图/UML/ER 图等
analyze_data_visualization	读取图表/仪表盘,提取洞察与趋势
ui_to_artifact	UI 截图转代码/提示词/规格说明/描述
ui_diff_check	比较两张 UI 截图差异

图片输入统一支持三种形式:本地路径、HTTP(S) URL、data:image/...;base64,... URI。 URL 与本地路径都会先在本地下载/读取并转 base64,以 data URI 内联发送,规避模型后端拉取外网图片超时。

配置

通过环境变量配置后端服务:

环境变量	说明	默认值
OLLAMA_BASE_URL	OpenAI 兼容服务根地址	http://localhost:11434
OLLAMA_API_KEY	Bearer 鉴权密钥	(空)
OLLAMA_MODEL	视觉模型名	doubao-seed-2.0-code

变量名仍沿用 OLLAMA_* 以保持向后兼容,实际已不依赖 Ollama 原生接口, 而是走标准 OpenAI /chat/completions。

安装

需 Python ≥ 3.10 与 uv。

cd 识图mcp
uv sync          # 安装依赖
uv run vision-mcp --help        # 验证可运行

客户端配置

Claude Desktop / Cline / Roo Code

{
  "mcpServers": {
    "vision-mcp": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "--directory", "/Volumes/samsungssd/code/temp/识图mcp", "vision-mcp"],
      "env": {
        "OLLAMA_BASE_URL": "https://ark.cn-beijing.volces.com/api/coding/v3",
        "OLLAMA_API_KEY": "你的ARK_API_KEY",
        "OLLAMA_MODEL": "doubao-seed-2.0-code"
      }
    }
  }
}

ZCode

{
  "mcpServers": {
    "vision-mcp": {
      "command": "uv",
      "args": ["run", "--directory", "/Volumes/samsungssd/code/temp/识图mcp", "vision-mcp"],
      "env": {
        "OLLAMA_BASE_URL": "https://ark.cn-beijing.volces.com/api/coding/v3",
        "OLLAMA_API_KEY": "你的ARK_API_KEY",
        "OLLAMA_MODEL": "doubao-seed-2.0-code"
      }
    }
  }
}

提示:--directory 指向本项目的绝对路径,请按实际位置修改。也可用 uvx --from /path/to/识图mcp vision-mcp。

使用示例

在客户端对话中直接提到图片路径/URL 即可,例如:

• "这张图 demo.png 里有什么?" → 触发 image_analysis
• "提取这张终端报错截图的文本" → 触发 extract_text_from_screenshot
• "对比 v1.png 和 v2.png 两个界面的差异" → 触发 ui_diff_check

开发与测试

uv sync
# 直接以 stdio 模式运行(可用 MCP inspector / 客户端连接)
uv run vision-mcp