# 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](https://docs.astral.sh/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 的备用方案"。

## 快速开始

```bash
# 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` 方式:

```bash
pip install -r requirements.txt
```

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

```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` 会让克隆者执行其中的启动命令,这是正常的(需要用户同意信任),但也请确认你只提交了自己写的脚本