vision-mcp

一个基于 MCP（Model Context Protocol）的多模态视觉服务，为不具备原生视觉能力的编码模型补充“看图”能力。

它通过 OpenAI SDK + OpenAI-compatible API 对接支持视觉的模型厂商，把截图、技术图、图表和视频帧转换为高质量文本结果，供 Cursor、Claude Code、Cline、VS Code Copilot 或其他 MCP 客户端继续推理和编码。

功能概览

当前提供 8 个 MCP tools：

• ui_to_artifact
  • 将 UI 截图转换为代码、设计提示词、设计规范或自然语言描述
• extract_text_from_screenshot
  • 从截图中提取文字，适合代码、终端输出、文档和通用文本 OCR
• diagnose_error_screenshot
  • 解析错误弹窗、堆栈和日志截图，输出定位与修复建议
• understand_technical_diagram
  • 解读架构图、流程图、UML、ER 图等技术图纸
• analyze_data_visualization
  • 阅读图表/仪表盘，提炼趋势、异常与业务要点
• ui_diff_check
  • 对比两张 UI 截图，识别视觉差异与实现偏差
• image_analysis
  • 通用图像理解能力，适合作为专项工具未覆盖时的 fallback
• video_analysis
  • 支持本地视频分析；当 provider 声明支持原生视频时发送 video_url，否则自动 fallback 为关键帧抽取

通过 npx 使用（无需 clone 仓库）

vision-mcp 已发布到 npm，你可以不 clone 仓库，直接通过 npx 一键运行：

npx -y vision-mcp

在 MCP 客户端中配置：

VS Code Copilot

{
  "servers": {
    "visionMcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "vision-mcp"]
    }
  },
  "inputs": [
    {
      "type": "promptString",
      "id": "api-key",
      "description": "Vision API Key",
      "password": true
    },
    {
      "type": "promptString",
      "id": "api-base-url",
      "description": "API Base URL",
      "password": false
    },
    {
      "type": "promptString",
      "id": "model",
      "description": "Vision Model Name",
      "password": false
    }
  ]
}

或在项目中的 .vscode/mcp.json 里配置并直接指定环境变量：

{
  "servers": {
    "visionMcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "vision-mcp"],
      "env": {
        "VISION_API_BASE_URL": "https://dashscope.aliyuncs.com/compatible-mode/v1",
        "VISION_API_KEY": "你的 Key",
        "VISION_MODEL": "qwen3.6-plus",
        "VISION_SUPPORTS_NATIVE_VIDEO": "true"
      }
    }
  }
}

Cursor (.cursor/mcp.json)

{
  "mcpServers": {
    "vision-mcp": {
      "command": "npx",
      "args": ["-y", "vision-mcp"],
      "env": {
        "VISION_API_BASE_URL": "https://dashscope.aliyuncs.com/compatible-mode/v1",
        "VISION_API_KEY": "YOUR_API_KEY",
        "VISION_MODEL": "qwen3.6-plus",
        "VISION_SUPPORTS_NATIVE_VIDEO": "true"
      }
    }
  }
}

Claude Code

{
  "mcpServers": {
    "vision-mcp": {
      "command": "npx",
      "args": ["-y", "vision-mcp"],
      "env": {
        "VISION_API_BASE_URL": "https://dashscope.aliyuncs.com/compatible-mode/v1",
        "VISION_API_KEY": "YOUR_API_KEY",
        "VISION_MODEL": "qwen3.6-plus"
      }
    }
  }
}

Cline

{
  "mcpServers": {
    "vision-mcp": {
      "command": "npx",
      "args": ["-y", "vision-mcp"],
      "env": {
        "VISION_API_BASE_URL": "https://dashscope.aliyuncs.com/compatible-mode/v1",
        "VISION_API_KEY": "YOUR_API_KEY",
        "VISION_MODEL": "qwen3.6-plus"
      }
    }
  }
}

Windows 用户注意：如果 MCP 客户端无法正确解析 npx 命令，可改用：

{
  "command": "cmd",
  "args": ["/c", "npx", "-y", "vision-mcp"]
}

本地开发模式

npm install
npm run build
npm start

配置

复制 .env.example 为 .env：

cp .env.example .env

必填配置

VISION_API_BASE_URL=
VISION_API_KEY=
VISION_MODEL=

可选配置

VISION_SUPPORTS_NATIVE_VIDEO=false
VISION_NATIVE_VIDEO_FPS=2
VISION_MAX_IMAGES_PER_REQUEST=10
VISION_IMAGE_DETAIL=auto
VISION_TIMEOUT=60000

配置说明

| 变量 | 必填 | 默认值 | 说明 | |---|---|---:|---| | VISION_API_BASE_URL | 是 | - | OpenAI-compatible API base URL | | VISION_API_KEY | 是 | - | API Key | | VISION_MODEL | 是 | - | 模型名称 | | VISION_SUPPORTS_NATIVE_VIDEO | 否 | false | 是否声明提供商支持原生视频输入 | | VISION_NATIVE_VIDEO_FPS | 否 | 2 | 原生视频输入时透传给 provider 的 FPS hint，范围 0.1 - 10 | | VISION_MAX_IMAGES_PER_REQUEST | 否 | 10 | 单次请求最多图片数量 | | VISION_IMAGE_DETAIL | 否 | auto | 图片 detail：low / high / auto | | VISION_TIMEOUT | 否 | 60000 | 请求超时（毫秒） |

使用要求

• Node.js >= 18
• 如果需要 video_analysis 的关键帧提取，请确保系统安装：
  • ffmpeg
  • ffprobe

各工具输入摘要

| Tool | 主要参数 | |---|---| | ui_to_artifact | image, output_format?, extra_prompt? | | extract_text_from_screenshot | image | | diagnose_error_screenshot | image | | understand_technical_diagram | image, diagram_type? | | analyze_data_visualization | image | | ui_diff_check | image_before, image_after, description? | | image_analysis | image, prompt? | | video_analysis | video, prompt? |

视频能力说明

• VISION_SUPPORTS_NATIVE_VIDEO=false 时：默认从本地视频提取关键帧（首 / 中 / 尾），并将关键帧作为多张图片送入视觉模型分析
• VISION_SUPPORTS_NATIVE_VIDEO=true 时：直接把本地视频编码为带 MIME 的 Base64 Data URL，并按 provider 扩展格式发送 video_url
• 当前 native video 分支是为 OpenAI-compatible provider 扩展（如 DashScope/Bailian 的 video_url）准备的，不代表标准 OpenAI 官方 schema 原生支持视频

VS Code Copilot 中使用技巧

在非视觉模型下使用 Copilot Chat + vision-mcp 时：

1. 不要在 Chat 里粘贴图片（模型看不了）
2. 将图片保存到本地目录
3. 在 Chat 中用文件路径显式调用工具：

请用 extract_text_from_screenshot 工具处理 C:/path/to/screenshot.png

Copilot 会将文件路径传给 vision-mcp，由 vision-mcp 读取文件并调用视觉模型。

开发

npm run build
npm test

故障排查

启动时报缺少环境变量

检查以下变量是否存在：

• VISION_API_BASE_URL
• VISION_API_KEY
• VISION_MODEL

视频分析失败，提示找不到 ffmpeg

请安装 ffmpeg / ffprobe 并确保它们在系统 PATH 中。

模型请求超时

• 调大 VISION_TIMEOUT
• 降低图片数量或分辨率
• 检查模型厂商接口稳定性

返回认证错误

• 检查 VISION_API_KEY
• 检查 VISION_API_BASE_URL 是否与厂商要求匹配
• 检查 VISION_MODEL 是否存在并具备视觉能力

图片文件不存在或路径错误

vision-mcp 接受相对路径（相对于当前工作目录）和绝对路径。请确保路径正确，建议使用绝对路径。

许可证

MIT