qwen-vision-mcp

让 Claude Code 具备"看图"能力的 MCP 服务器。当主模型是纯文本模型(如 DeepSeek)时,通过本工具把图片交给 Qwen 视觉模型(默认阿里云 DashScope 的 qwen-vl-max)分析,再把结果返回给 Claude。

原理

Claude Code ──(MCP stdio)──> qwen-vision-server.py ──(base64 图片)──> DashScope API (qwen-vl-max)
     ▲                                                                         │
     └────────────────────── 返回文字描述 ◀──────────────────────────────────┘

• 主模型理解你的话、决定"该看图了",然后调用 analyze_image 工具
• qwen-vision-server.py 把图片文件 base64 编码,发给视觉模型,拿回文字描述
• 真正"看懂"图片的是 qwen 视觉模型,主模型负责调度和转述

前置要求

• Claude Code
• uv(推荐,自动装依赖、跨平台)。安装:
  • Windows:winget install astral-sh.uv 或 pip install uv
  • macOS/Linux:curl -LsSf https://astral.sh/uv/install.sh | sh
• 一个 DashScope(阿里云百炼)API Key,申请地址:https://bailian.console.aliyun.com

不想用 uv 也可以,见文末"不使用 uv 的备用方案"。

快速开始

# 1. 克隆仓库
git clone https://github.com/<你的用户名>/qwen-vision-mcp.git
cd qwen-vision-mcp

# 2. 设置你的 API Key —— 必须在"启动 claude 的那个终端"里设置
#    Windows (PowerShell)
$env:DASHSCOPE_API_KEY = "sk-你的key"
#    macOS / Linux (bash/zsh)
export DASHSCOPE_API_KEY="sk-你的key"

然后用 Claude Code 打开这个目录:

1. 首次打开会弹出信任提示"Do you trust the files in this folder?",选第一项: "Yes, proceed with MCP servers and hooks enabled"(允许项目里的 MCP 服务器)
2. 确认 qwen-vision 已连接:在 Claude Code 里输入 /mcp,应显示 qwen-vision 为 Connected
3. 直接给 Claude 发一张图片,或说:

用 qwen 看这张图,里面有什么?

自定义后端

默认走阿里云 DashScope。想用其他兼容 OpenAI 的视觉接口(比如自建 GPU 服务),改 .mcp.json 里 env 的三个变量:

变量	默认值	说明
DASHSCOPE_API_KEY	(必须填)	API Key,支持 ${环境变量} 占位
QWEN_BASE_URL	https://dashscope.aliyuncs.com/compatible-mode/v1	接口地址
QWEN_MODEL	qwen-vl-max	模型名

项目结构

qwen-vision-mcp/
├── qwen-vision-server.py   # MCP 服务器脚本(核心,含 uv 内联依赖声明)
├── .mcp.json               # MCP 配置(项目作用域,Claude Code 自动加载)
├── requirements.txt        # 备用方案的 Python 依赖(python 命令时用)
├── README.md               # 本文档
└── .gitignore              # 防止 key 泄漏

不使用 uv 的备用方案

如果你不想装 uv,改成 python 方式:

pip install -r requirements.txt

然后把 .mcp.json 里的启动命令改成:

"command": "python",
"args": ["qwen-vision-server.py"]

macOS/Linux 若 python 不存在,改用 python3,并相应改 command。

常见问题

Q: analyze_image 工具没出现? A: 先确认 /mcp 里 qwen-vision 是 Connected;不是就重启 Claude Code。若完全没加载,大概率是没通过首次信任提示,重开一次选"允许 MCP servers"。

Q: 报 401 Unauthorized? A: API Key 不对或没设置。确认启动 claude 的终端里 DASHSCOPE_API_KEY 已 export(每次新开终端都要再设,或用 setx 持久化)。

Q: 回答是空的? A: 若换用了推理型模型(如 Qwen3.5),答案可能放在 reasoning_content,脚本已自动兜底。仍为空就检查 key 余额、模型名。

Q: 不想每次设环境变量? A: Windows 可 setx DASHSCOPE_API_KEY "sk-你的key" 持久化到用户环境;或改 .mcp.json 直接填 key,但千万别提交到 git(见安全提醒)。

安全提醒

• 不要把 API Key 写进代码或提交到 GitHub,否则别人能用你的额度替你的 key 买单
• 本项目 .gitignore 已排除 .env、*.key 等文件,但 .mcp.json 里若手填了 key,提交前务必改回 ${DASHSCOPE_API_KEY}
• .mcp.json 会让克隆者执行其中的启动命令,这是正常的(需要用户同意信任),但也请确认你只提交了自己写的脚本