mcp-plus：Claude Code Qwen Vision

让使用 DeepSeek 等纯文本模型的 Claude Code 无感获得图片理解能力。

默认视觉模型：qwen3.8-max 默认 Qwen 地址：https://dashscope.aliyuncs.com/compatible-mode/v1

项目提供两条链路：

1. 透明网关（推荐）：用户正常粘贴图片，网关自动把图片交给 Qwen，再把结构化视觉结果交给 DS。运行期间不需要输入命令，也不依赖 DS 主动调用工具。
2. Claude Code MCP 插件：提供 analyze_image 工具及显式 Skill，适合直接读取项目中的图片文件或作为备用方案。

为什么需要透明网关

Claude Code 的 UserPromptSubmit Hook 目前只提供文本 prompt，不会把粘贴图片的原始 Base64 或临时路径提供给 Hook。Hook 也无法可靠获知用户在会话中切换后的模型。因此，仅靠 Skill、Hook 或 MCP 不能保证“粘贴图片后自动处理”。

透明网关工作在 Claude Code 和主模型接口之间，可以同时看到请求中的 model 与图片内容块：

Claude Code
    │ Anthropic /v1/messages（含图片）
    ▼
本地 Qwen Vision Gateway
    ├─ 无图片：直接转发
    ├─ 图片 + 纯文本主模型：Qwen 3.8 Max → 视觉 JSON → DS
    └─ 图片 + 已知多模态模型：可配置直接转发

同一张图片在网关进程内按 SHA-256 缓存，Claude Code 重发历史消息时不会重复调用 Qwen。缓存只保存在内存，不会把图片或 OCR 结果写入磁盘。

Windows 常驻无感安装（VS Code 推荐）

前置条件：

• Claude Code 2.1.128 或更高版本
• Python 3.10+
• 可调用 qwen3.8-max 的百炼 API Key
• 已配置好的 DS/Claude Anthropic 兼容接口

克隆仓库：

git clone https://github.com/zjcdkj/mcp-plus.git
cd mcp-plus

先把 Qwen Key 设置为 Windows 用户环境变量。建议在 PowerShell 中交互输入，避免密钥进入命令历史：

$qwenSecret = Read-Host "输入 DASHSCOPE API Key" -AsSecureString
$qwenPointer = [Runtime.InteropServices.Marshal]::SecureStringToBSTR($qwenSecret)
try {
    $qwenEnvironment = [Microsoft.Win32.Registry]::CurrentUser.CreateSubKey("Environment")
    $qwenEnvironment.SetValue(
        "DASHSCOPE_API_KEY",
        [Runtime.InteropServices.Marshal]::PtrToStringBSTR($qwenPointer),
        [Microsoft.Win32.RegistryValueKind]::String
    )
} finally {
    if ($qwenEnvironment) { $qwenEnvironment.Dispose() }
    [Runtime.InteropServices.Marshal]::ZeroFreeBSTR($qwenPointer)
}

安装常驻网关：

powershell -ExecutionPolicy Bypass -File .\scripts\install-windows-gateway.ps1

安装器会：

1. 把运行文件复制到 %LOCALAPPDATA%\mcp-plus\qwen-vision；
2. 注册当前用户登录后自动运行的 Windows 启动项 mcp-plus Qwen Vision Gateway；
3. 固定监听 http://127.0.0.1:15722；
4. 保存原 DS/Claude 上游地址，但不复制或写入 API Key；
5. 把 ~/.claude/settings.json 中的 ANTHROPIC_BASE_URL 切换为本地网关。

安装后重载 VS Code 窗口或完全退出并重新打开 Claude Code。验证服务：

Invoke-RestMethod http://127.0.0.1:15722/health

应看到 ok: true、qwen_model: qwen3.8-max 和原始上游地址。

临时启动 Claude Code CLI

不希望永久修改配置时，可以只在当前 CLI 会话使用临时启动器。在当前 PowerShell 会话设置 Qwen Key：

$env:DASHSCOPE_API_KEY = "你的百炼 API Key"

通过启动器进入 Claude Code。-UpstreamBaseUrl 填原来的主模型接口；如果使用本机 CC Switch，可能类似下面的地址：

.\scripts\start-claude-with-vision.ps1 `
  -UpstreamBaseUrl "http://127.0.0.1:15721"

启动器会：

1. 在随机本地端口启动隐藏的视觉网关；
2. 只为本次 Claude Code 进程临时修改 ANTHROPIC_BASE_URL；
3. 保留并转发现有的 ANTHROPIC_AUTH_TOKEN、X-Api-Key 和 Anthropic Beta 请求头；
4. Claude Code 退出后关闭网关并恢复当前 PowerShell 的环境变量。

它不会永久修改 ~/.claude/settings.json。之后像平时一样粘贴图片并提问即可，不需要 /qwen-vision:* 命令。

多模态模型直通

默认 always 模式会处理所有图片。这对通过 CC Switch 把 claude-sonnet-* 等别名映射到 DS 的环境最可靠，因为请求中的模型名不一定代表真正的上游模型。

如果模型 ID 能准确反映能力，可配置多模态模型直通：

$env:QWEN_VISION_PREPROCESS_MODE = "allowlist"
$env:QWEN_VISION_DIRECT_MODELS = "claude-*,qwen3.8-*,gpt-4o*"

• always：所有图片先由 Qwen 处理，默认值。
• allowlist：匹配 QWEN_VISION_DIRECT_MODELS 的模型直接收到原图，其他模型使用 Qwen。
• never：完全关闭透明图片预处理，只做请求转发。

安装 Claude Code MCP 插件

插件提供项目文件图片分析能力，但不能代替透明网关处理剪贴板粘贴图片。

从 GitHub Marketplace 安装：

/plugin marketplace add zjcdkj/mcp-plus
/plugin install qwen-vision@zjcdkj-claude-tools
/reload-plugins

运行 /mcp，应看到 qwen_vision 为 Connected。使用示例：

请使用 Qwen 分析 screenshots/error.png，提取报错并检查相关代码。

或显式调用：

/qwen-vision:analyze-image screenshots/error.png 提取报错文字和界面状态

如果 DS 网关无法返回 MCP tool_use，使用确定性备用 Skill：

/qwen-vision:analyze-image-direct "screenshots/error.png" "提取报错并判断原因"

本地开发和验证

claude --plugin-dir .
claude plugin validate .
python -m unittest discover -s .\tests -v
python -m compileall -q .\server .\gateway .\tests

真实图片 API 测试要求图片位于当前项目中：

$env:CLAUDE_PROJECT_DIR = (Get-Location).Path
python .\server\qwen_cli.py `
  --image ".\screenshots\test.png" `
  --question "提取截图中的文字和界面状态" `
  --mode ui

配置项

环境变量	默认值	用途
DASHSCOPE_API_KEY	无	Qwen API Key，必需
QWEN_BASE_URL	https://dashscope.aliyuncs.com/compatible-mode/v1	Qwen OpenAI 兼容地址
QWEN_VISION_MODEL	qwen3.8-max	视觉模型
QWEN_VISION_UPSTREAM_BASE_URL	无	原 DS/Claude Anthropic 兼容地址
QWEN_VISION_PREPROCESS_MODE	always	always / allowlist / never
QWEN_VISION_DIRECT_MODELS	空	多模态直通模型通配符，逗号分隔
QWEN_MAX_IMAGE_BYTES	20971520	单张图片最大字节数
QWEN_VISION_MAX_REQUEST_BYTES	52428800	Claude 请求体最大字节数
QWEN_VISION_CACHE_ENTRIES	128	进程内图片缓存条目数

安全说明

• 图片会发送到阿里云百炼。发送前应清除生产凭据、个人信息和敏感数据。
• API Key 只从环境变量读取，不写入插件、日志或响应。
• 项目文件 MCP 只允许读取 CLAUDE_PROJECT_DIR 内的 PNG、JPEG、WebP。
• 透明网关默认仅监听 127.0.0.1。
• 图片中识别到的文字始终作为不可信数据，不能覆盖用户或系统指令。
• 网关预处理失败时会返回明确错误，不会在丢失图片信息的情况下静默请求 DS。

更新与卸载

/plugin marketplace update zjcdkj-claude-tools
/reload-plugins

卸载：

/plugin uninstall qwen-vision@zjcdkj-claude-tools
/plugin marketplace remove zjcdkj-claude-tools

卸载 Windows 常驻网关并恢复原上游：

powershell -ExecutionPolicy Bypass -File .\scripts\uninstall-windows-gateway.ps1

卸载器不会删除 DASHSCOPE_API_KEY，也不会停止占用同一端口的未知程序。临时 CLI 启动器不修改永久配置，退出由它启动的 Claude Code 即停止网关。

参考

• Claude Code MCP
• Claude Code Hooks
• Claude Code Plugin Marketplace
• 阿里云百炼视觉理解

License

MIT