Vision MCP Server

为缺少多模态能力的 LLM（如 DeepSeek）提供图片理解能力。通过 OpenAI-compatible API 将图片转发至视觉模型，以 MCP 工具形式暴露 describe_image，可接入任意支持 MCP 协议的 AI Agent（Claude Code、Cline、Continue.dev 等）。

一、配置方式

所有后端配置（API 地址、密钥、模型名）通过项目根目录的 .env 文件管理，无需在 MCP 注册时反复传入环境变量。修改配置后重启 Agent 即可生效。

1. 安装

uv venv && uv pip install -e .

2. 配置后端

复制配置模板并填入实际值：

cp .env.example .env

.env 文件内容：

VISION_API_BASE=https://api.siliconflow.cn/v1      # 视觉模型 API 地址
VISION_API_KEY=sk-your-key-here                      # API 密钥
VISION_MODEL=Qwen/Qwen3.6-35B-A3B                    # 模型名称
VISION_MAX_TOKENS=2000                                # 最大输出 token 数（可选）

.env 由 Server 启动时自动加载，修改后重启 Agent 即可生效，无需重新注册 MCP。

3. 注册到 AI Agent

方式 A（推荐）— 直接使用 .mcp.json

项目已内置 .mcp.json 文件，支持此格式的 Agent（Cline、Continue.dev 等）会自动识别：

{
  "mcpServers": {
    "vision": {
      "command": "uv",
      "args": ["run", "vision-mcp"]
    }
  }
}

方式 B — Claude Code 手动注册

claude mcp add-json -s user vision '{
  "command": "uv",
  "args": ["run", "vision-mcp"]
}'

所有方式均无需携带 env 字段，配置已由 .env 文件管理。

4. 验证

vision-mcp --help

确认 Agent 中 MCP Server 状态为已连接（Claude Code: claude mcp list → vision: vision-mcp - ✓ Connected）。

Related MCP server: Vision MCP Server

二、工作原理

User: "看看这张截图"
  → AI Agent (DeepSeek, 无视觉)
    → 调用 describe_image 工具
      → Vision MCP Server: 读取本地图片 → Base64 → POST 视觉模型 API
        ← 返回文字描述
  → AI Agent 基于描述回答用户

三、工具说明

describe_image — 理解图片内容

• 支持格式：PNG / JPG / JPEG / GIF / WebP / BMP

• 单文件限制：≤ 20 MB

vision_ping — 诊断连通性

返回服务器状态信息，用于排查 MCP 通信是否正常。

echo '{"jsonrpc":"2.0","id":1,"method":"tools/call",\
  "params":{"name":"vision_ping","arguments":{"msg":"hello"}}}' | vision-mcp

四、使用示例

User: 看看 @error_screenshot.png 里的报错信息
User: 分析 @architecture.png 的系统设计有什么问题
User: 把 @data_table.png 转成 markdown 表格
User: @chart.png 描述数据变化趋势，控制在 200 字以内

五、更新配置

修改 .env 文件后重启 AI Agent 即可生效，无需重新注册 MCP。

如需更换 Provider 的 API 地址，可参考以下配置：

常见问题

Failed to connect？

1. 确认 vision-mcp --help 可执行

2. 检查 API 连通性：curl $VISION_API_BASE/models

3. 运行 vision-mcp 查看 stderr 日志

返回乱码或空内容？

• 尝试将图片转为 PNG 格式

• 缩小图片尺寸（Base64 后体积增大约 33%）

• 更换更强大的视觉模型

图片数据会留存吗？

不会。图片仅通过 Base64 编码后 HTTPS 发送至视觉 API，Server 不做本地存储或缓存。使用公网 API 时注意勿传入敏感图片。