qwen-vision-mcp

Claude Code 视觉降级识别 —— 通过 MCP 让纯文本模型（如 DeepSeek 系列）调用千问视觉模型（DashScope 阿里云百炼）识别图片，把返回的文字描述喂回当前模型继续推理。

当你的 Claude Code 使用了一个没有视觉能力的模型（收到图片只能看到 [Unsupported Image]），本工具会在模型收到图片时自动降级：调用千问视觉模型识别图片内容，再以文字形式交回模型。

功能特性

• recognize_image MCP 工具：读本地图片 → base64 → 调千问视觉模型 → 返回文字描述
• 配套 Skill：收到图片但模型看不了时自动触发，引导模型调用工具
• 模型可配置：默认模型 qwen3.5-omni-plus-2026-03-15，可通过环境变量 QWEN_VISION_DEFAULT_MODEL 修改，也可在单次调用时传 model 参数
• Windows 环境变量兜底：进程未继承用户级环境变量时，自动从注册表 HKCU\Environment 读取
• 友好错误提示：无 key / 文件不存在 / 图片过大 / API 调用失败均返回可读中文错误

架构

模型收到图片但自己无法查看
   │  (Skill: recognize-image 触发)
   ▼
MCP 工具 recognize_image(path, prompt, model)
   │  读图 → base64 → data URI
   ▼
DashScope OpenAI 兼容端点（千问视觉模型 Qwen-VL）
   │  返回文字描述
   ▼
模型把返回文字当作"看"到的内容，继续回答用户

环境要求

• Python 3.10+
• Claude Code（或任意支持 MCP 与 Skill 的客户端）
• 阿里云百炼（DashScope）API Key：https://bailian.console.aliyun.com/

安装

# 1. 克隆仓库
git clone <你的仓库地址> qwen-vision-mcp
cd qwen-vision-mcp

# 2. 创建虚拟环境并安装依赖
python -m venv .venv
# Windows:
.venv\Scripts\python -m pip install -r requirements.txt
# macOS / Linux:
# .venv/bin/python -m pip install -r requirements.txt

# 3. 设置 API Key（任选其一）
#    方式 A：设置到当前环境
export DASHSCOPE_API_KEY=sk-xxxx
#    方式 B：写入 ~/.claude/settings.json 的 env 段
#    方式 C（Windows）：系统"环境变量"（用户级）

# 4. 注册 MCP server（用户级，所有项目可用）
claude mcp add qwen-vision --scope user -- \
  <venv-python 绝对路径> <仓库绝对路径>/server.py
# 例如 Windows：
# claude mcp add qwen-vision --scope user -- \
#   D:/qwen-vision-mcp/.venv/Scripts/python D:/qwen-vision-mcp/server.py

# 5. 安装配套 Skill（复制到 Claude Code 的 skills 目录）
#    Windows / macOS / Linux: ~/.claude/skills/
cp -r skill/recognize-image ~/.claude/skills/

安装完成后重启 Claude Code，运行 claude mcp list 应能看到 qwen-vision ✓ Connected。

使用说明

1. 重启 Claude Code 后，直接向模型发送一张图片（粘贴路径、拖拽附件等）。
2. 模型自己无法查看图片时，recognize-image Skill 会自动触发，引导模型调用 recognize_image 工具。
3. 工具返回的文字描述就是模型"看到"的内容，模型会基于它继续回答你。

也可以直接要求模型手动调用：

请用 recognize_image 识别 <图片路径>，我想了解 ...

工具参数：

参数	说明
path	图片绝对路径（png / jpg / jpeg / webp / bmp / gif）
prompt	想从图片中了解什么，默认"请详细描述这张图片的内容"
model	千问视觉模型名，默认取 QWEN_VISION_DEFAULT_MODEL，未设置则用 qwen3.5-omni-plus-2026-03-15

配置

环境变量	必填	说明
DASHSCOPE_API_KEY	是	阿里云百炼 DashScope API Key
QWEN_VISION_DEFAULT_MODEL	否	默认视觉模型名（如 qwen-vl-max），缺省 qwen3.5-omni-plus-2026-03-15

单次调用模型优先顺序：显式 model 参数 > QWEN_VISION_DEFAULT_MODEL 环境变量 > 内置默认值。

卸载

# 1. 移除 MCP 注册
claude mcp remove qwen-vision

# 2. 删除 Skill
rm -rf ~/.claude/skills/recognize-image

# 3. 删除仓库目录
rm -rf qwen-vision-mcp

# 4. （可选）移除环境变量 DASHSCOPE_API_KEY / QWEN_VISION_DEFAULT_MODEL

常见问题（FAQ）

为什么 requirements.txt 固定 mcp<2？

mcp 2.0.0 移除了 mcp.server.fastmcp.FastMCP，本工具基于 FastMCP 编写，因此固定到 1.x。

Windows 下设置了用户环境变量但进程读不到？

本工具会通过注册表 HKCU\Environment 兜底读取 DASHSCOPE_API_KEY 和 QWEN_VISION_DEFAULT_MODEL，即使 Claude Code 进程早于环境变量设置而启动，也能读到。

图片大小限制？

单张图片上限 8MB（server.py 中 MAX_BYTES）。超大图片请先压缩或裁剪。

支持视频吗？

暂不支持。后续版本计划 recognize_video（ffmpeg 抽帧后逐帧识别）。

License

MIT