qwen-vision-mcp

qwen-vision-mcp

让任何文本模型（Claude、GLM、GPT、Gemini...）通过 MCP 按需"看图和看视频"。后端走阿里云 DashScope 的 qwen3.7-plus，通过 Anthropic 兼容接口调用——qwen 原生支持图片和视频理解。

为什么需要这个

文本模型（GLM-4、Claude Haiku、GPT-4o-mini 等便宜/快的模型）不会直接看图。但很多任务（截图报错、UI 调试、图表分析、文档 OCR）需要视觉理解。

qwen-vision-mcp 把 qwen 视觉模型包装成一个 MCP 工具 look(image, question)，让任何 MCP 兼容的 Agent 按需调用——只在需要时才"看一眼"，主对话仍由你便宜的文本模型驱动。

特色

• 🧠 有状态多轮持久：同一会话内 qwen 会记得之前所有图片和问答，支持"再看一眼刚才那张图"。
• 🚆 自动 trim 防超限：单次请求体超过 DashScope 6MB 上限时，自动把较早的 image/video block 替换成文字指针（保留文字 question + assistant 回复），长程多模态对话不崩。
• 🎬 视频原生支持：qwen3.7-plus 通过 anthropic 兼容接口直接吃整个视频（不是逐帧），52s 视频 ≈ 31K tokens。硬 cap 60s / base64 后 6.25MB，超限直接报错不压缩。
• 🖼️ 大图自动压缩：本地大图 / 剪贴板截图（> 1.5MB）发送前自动用系统 sips 缩到长边 1568px + 转 JPEG q85，避免 base64 膨胀后撑爆 6MB 上限（25MB HEIC 实测压到 ~330KB）。macOS 自带 sips 零依赖；非 macOS fallback 到直接 base64。
• 🔌 按进程隔离：每个客户端会话独立一个 MCP server 进程，messages 不串台。
• 📦 极简依赖：只依赖 @modelcontextprotocol/sdk，Bun 直接跑 .ts，无编译步骤。
• 🔁 失败干净回滚：网络异常 / HTTP 错误时自动 pop 掉刚 push 的 user message，历史不污染。

工作原理

文本模型 (GLM/Claude/GPT)  ──MCP stdio──▶  qwen-vision-mcp server
                                                  │
                                                  ▼
                                          DashScope qwen 视觉模型
                                         (Anthropic 兼容接口)

主模型决定"什么时候需要看图、问什么"，qwen 只负责"看一眼并回答具体问题"。模型行为由工具 description 引导（要拆解、要聚焦、要多轮追问）。

安装

需要 Bun 运行时 + DashScope API Key（阿里云百炼控制台 获取）。

git clone <your-fork-url> qwen-vision-mcp
cd qwen-vision-mcp
bun install                    # 装 @modelcontextprotocol/sdk
cp .env.example .env           # 填入 QWEN_API_KEY

.env 内容：

QWEN_BASE_URL=https://dashscope.aliyuncs.com/apps/anthropic/v1
QWEN_API_KEY=sk-你的-key
QWEN_MODEL=qwen3.7-plus
QWEN_MAX_TOKENS=1024
QWEN_MAX_REQUEST_BYTES=5000000
QWEN_COMPRESS_THRESHOLD=1500000
QWEN_IMAGE_MAX_EDGE=1568

接入 MCP 客户端

Claude Code

在 ~/.claude.json（或项目级 .mcp.json）的 mcpServers 里加：

{
  "mcpServers": {
    "qwen-vision": {
      "command": "bun",
      "args": ["run", "/absolute/path/to/qwen-vision-mcp/index.ts"],
      "env": { "QWEN_API_KEY": "sk-..." }
    }
  }
}

Cursor / Continue / 其它 MCP 客户端

任何支持 stdio MCP server 的客户端都能接入，配置格式大同小异——指定 bun 为 command，run /path/to/index.ts 为 args，把 QWEN_API_KEY 放到 env 里。

Proma

在 Proma 工作区的 mcp.json 里加：

"qwen-vision": {
  "type": "stdio",
  "command": "bun",
  "args": ["run", "/absolute/path/to/qwen-vision-mcp/index.ts"],
  "env": { "QWEN_API_KEY": "sk-...", "QWEN_MODEL": "qwen3.7-plus" },
  "enabled": true
}

暴露的工具

look(image, question) — 有状态

让 qwen 看一张图片回答你提出的具体问题。

• image: 本地绝对路径 / http(s) URL / data:image;base64,...
• question: 针对该图片的具体、聚焦的问题

重要：这个工具是有状态的。同一会话内 qwen 会记得前面所有图片和问答。

• 同一张图追问细节 → 直接连续调用，qwen 自带上下文
• 切换到完全无关的新图 → 先调 reset_vision_session 清空历史，避免旧图污染

watch(video, question) — 有状态，视频

让 qwen 看一段视频回答问题。qwen 直接吃整个视频（不是逐帧），原生支持视频理解。

• video: 本地绝对路径 / http(s) URL / data:video;base64,...
• question: 针对该视频的具体、聚焦的问题

硬 cap（超限直接报错，不自动压缩）：

• 时长 ≤ 60 秒
• 原始 ≤ ~4.7MB（base64 后 < 6.25MB，DashScope 请求体 6MB 硬限制）

上下文成本警告：1 分钟视频 ≈ 30K tokens。复杂视频分析建议委托子 agent（如 Proma 的 collaboration.delegate_agent）——子 agent 在独立上下文里多轮追问，只把最终结论返回主对话，避免视频 token 撑爆主上下文。

reset_vision_session() — 清空历史

何时调：当前图片讨论完、要切到无关新图时，或想从干净状态重启时。 何时不调：同一张图的多轮追问、相关图片延续讨论时。

配置项

| 环境变量 | 默认 | 说明 | |---|---|---| | QWEN_BASE_URL | https://dashscope.aliyuncs.com/apps/anthropic/v1 | DashScope Anthropic 兼容入口 | | QWEN_API_KEY | 必填 | DashScope API Key | | QWEN_MODEL | qwen3.7-plus | 视觉模型 id（可改 qwen-vl-max-latest 等） | | QWEN_MAX_TOKENS | 1024 | 单次回复 token 上限 | | QWEN_MAX_REQUEST_BYTES | 5000000 | 单次请求体字节上限（DashScope 硬上限 6MB） | | QWEN_ENABLE_THINKING | false | 推理模型 thinking 开关。默认关（视觉问答 7-10x 提速）；复杂图表分析/推理题场景设 true | | QWEN_COMPRESS_THRESHOLD | 1500000 | 原图字节超过此值则用 sips 缩放压缩成 JPEG（防 base64 膨胀撑爆 6MB 请求体） | | QWEN_IMAGE_MAX_EDGE | 1568 | 压缩时长边像素上限（qwen-vl 推荐尺寸，再高也是浪费 token） | | QWEN_MAX_VIDEO_SECONDS | 60 | 视频时长上限（ffprobe 不可用时跳过时长检查） | | QWEN_MAX_VIDEO_BYTES | 6250000 | 视频 base64 后字节上限（DashScope 请求体 6MB 硬限留余量） |

已知限制

• 进程隔离 ≠ 跨重启持久化：进程被杀（客户端退出、crash）→ 内存里的 messages 丢失 = 自动 reset。同一会话活跃期间的持久化没问题，跨重启做不到。
• URL 图片需 DashScope 服务端能访问：内网图床 / 被墙的 URL 会报 Failed to download multimodal content，用本地路径最稳。
• 历史图片 trim 策略：超过 QWEN_MAX_REQUEST_BYTES 时从最早的 image 开始替换成文字指针，保留最后 1 张图和所有文字。这意味着 qwen 对"很久之前的图"会失去视觉记忆（但仍能从对话历史里"读"自己之前的描述）。
• 压缩依赖 macOS sips：大图缩放走系统命令 sips（/usr/bin/sips），macOS 自带。Linux/Windows 没有 sips，会 fallback 到直接 base64 原图 —— 此时单张超大图仍可能触发 6MB 上限，需要换 sharp 等跨平台方案。
• 视频不做自动压缩：cap 60s / base64 后 6.25MB，超限直接报错。设计取舍——视频压缩不 general（sips 只能处理图，ffmpeg 要额外装），让用户自行用 ffmpeg 处理。时长检查依赖 ffprobe（ffmpeg 套件），不可用时只检查大小。
• 视频上下文成本高：1 分钟视频 ≈ 30K tokens，多次 watch 会迅速占满主对话上下文。复杂场景请委托子 agent 承载。

故障排查

| 错误 | 原因 | 解决 | |---|---|---| | 工具不注入 / 启动无报错 | 调用此 MCP 的 agent 对 index.ts 所在目录无读权限（command 写绝对路径只是必要条件，agent 的运行环境还必须能访问到该文件） | 确保调用方 agent 能读到 .ts 文件本身。Proma 下若脚本放在 ~/Documents 等 macOS 保护目录，把该目录加入工作区可访问目录即可（无需改「系统设置 → 隐私」）；终端 / Claude Code 等加载用户 shell 的客户端一般无此问题 | | 404 | BASE_URL 错了 | 确认用 /apps/anthropic/v1 而不是 /compatible-mode/v1 | | model not found | QWEN_MODEL id 错了 | 查 DashScope 文档 确认 id | | Failed to download multimodal content | URL 图片 DashScope 服务端访问不到 | 改用本地路径 | | Exceeded limit on max bytes to request body : 6291456 | 请求体超 6MB（DashScope 硬上限） | 单张大图会自动 sips 压缩；若仍报错说明历史累积太多 → 调 reset_vision_session 清历史，或调小 QWEN_MAX_REQUEST_BYTES / QWEN_COMPRESS_THRESHOLD | | 响应慢（每次 10s+） | qwen3.7-plus 是推理模型，默认每轮生成几百 token thinking | 已默认关 thinking；确认 QWEN_ENABLE_THINKING=false（或换非推理模型如 qwen-vl-max-latest） | | 视频过大 / 视频过长 | 超过 cap（60s 或 base64 后 6.25MB） | 用 ffmpeg 压缩：ffmpeg -i in.mp4 -b:v 500k -t 60 out.mp4；或截短 |

开发与测试

# 启动 server（stdio 模式，等待客户端连接）
bun run index.ts

# 协议层冒烟测试（发 initialize + tools/list）
( \
  printf '%s\n' \
    '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' \
    '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
    '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' ; \
  sleep 2 \
) | bun run index.ts

# 端到端测试（看一张本地图）
( \
  printf '%s\n' \
    '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' \
    '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
    '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"look","arguments":{"image":"/tmp/test.png","question":"一句话描述这张图"}}}' ; \
  sleep 15 \
) | bun run index.ts

# 验证 sips 大图压缩（用系统桌面图模拟极端大图输入；期望输出 < 1MB）
SRC=$(ls -S "/System/Library/Desktop Pictures/"*.heic 2>/dev/null | head -1)
sips -Z 1568 -s format jpeg -s formatOptions 85 "$SRC" --out /tmp/qwen-compress-test.jpg
ls -lh /tmp/qwen-compress-test.jpg   # 25MB HEIC 实测 ~330KB
rm -f /tmp/qwen-compress-test.jpg

License

MIT