mcp-plus: Claude Code Qwen Vision

Enables Claude Code, which typically uses plain-text models like DeepSeek, to seamlessly gain image understanding capabilities.

Default vision model: qwen3.8-max Default Qwen endpoint: https://dashscope.aliyuncs.com/compatible-mode/v1

The project provides two paths:

1. Transparent Gateway (Recommended): Users paste images normally. The gateway automatically sends the image to Qwen and passes the structured vision result to DS. No commands or DS tool invocations are required during use.

2. Claude Code MCP Plugin: Provides an analyze_image tool and explicit Skills, suitable for directly reading image files in the project or as a fallback solution.

Why a Transparent Gateway is Needed

Claude Code's UserPromptSubmit Hook currently only provides the text prompt; it does not expose the raw Base64 or temporary path of pasted images to the Hook. The Hook also cannot reliably determine which model the user has switched to during a session. Therefore, relying solely on Skills, Hooks, or MCP cannot guarantee automatic processing of pasted images.

The transparent gateway operates between Claude Code and the main model interface, allowing it to simultaneously see the model and image content blocks in the request:

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

The same image is cached by SHA-256 within the gateway process, so Qwen is not called repeatedly when Claude Code resends historical messages. The cache resides only in memory; images or OCR results are never written to disk.

Permanent Silent Installation on Windows (Recommended for VS Code)

Prerequisites:

• Claude Code 2.1.128 or higher

• Python 3.10+

• A Bailian API Key capable of calling qwen3.8-max

• A configured DS/Claude Anthropic compatible endpoint

Clone the repository:

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

First, set the Qwen Key as a Windows user environment variable. It is recommended to input it interactively in PowerShell to avoid the key entering the command history:

$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)
}

Install the persistent gateway:

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

The installer will:

1. Copy the runtime files to %LOCALAPPDATA%\mcp-plus\qwen-vision;

2. Register a Windows startup item mcp-plus Qwen Vision Gateway that runs automatically after the current user logs in;

3. Listen permanently on http://127.0.0.1:15722;

4. Save the original DS/Claude upstream address, but will not copy or write the API Key;

5. Switch ANTHROPIC_BASE_URL in ~/.claude/settings.json to the local gateway.

After installation, reload the VS Code window or fully exit and reopen Claude Code. Verify the service:

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

You should see ok: true, qwen_model: qwen3.8-max, and the original upstream address.

Temporary Startup for Claude Code CLI

If you prefer not to modify the configuration permanently, you can use a temporary launcher only for the current CLI session. Set the Qwen Key in the current PowerShell session:

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

Enter Claude Code via the launcher. Fill -UpstreamBaseUrl with the original main model endpoint; if using local CC Switch, the address might look like the following:

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

The launcher will:

1. Start a hidden vision gateway on a random local port;

2. Temporarily modify ANTHROPIC_BASE_URL only for this Claude Code process;

3. Preserve and forward the existing ANTHROPIC_AUTH_TOKEN, X-Api-Key, and Anthropic Beta request headers;

4. Close the gateway and restore the current PowerShell's environment variables when Claude Code exits.

It will not permanently modify ~/.claude/settings.json. Afterward, just paste images and ask questions as usual; no /qwen-vision:* commands are needed.

Multimodal Model Passthrough

The default always mode processes all images. This is most reliable for environments where CC Switch maps aliases like claude-sonnet-* to DS, as the model name in the request may not accurately reflect the actual upstream model.

If the model ID accurately reflects its capabilities, you can configure multimodal model passthrough:

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

• always: All images are first processed by Qwen. Default value.

• allowlist: Models matching QWEN_VISION_DIRECT_MODELS receive the original image directly; other models use Qwen.

• never: Completely disable transparent image preprocessing; only forward requests.

Installing the Claude Code MCP Plugin

The plugin provides image analysis capabilities for project files but cannot replace the transparent gateway for handling clipboard-pasted images.

Install from the GitHub Marketplace:

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

Run /mcp, you should see qwen_vision as Connected. Usage example:

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

Or call explicitly:

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

If the DS gateway cannot return MCP tool_use, use the deterministic fallback Skill:

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

Local Development and Verification

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

Real image API testing requires the image to be located within the current project:

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

Configuration Options

Security Notes

• Images are sent to Alibaba Cloud Bailian. Clear production credentials, personal information, and sensitive data before sending.

• API Keys are only read from environment variables, never written to plugins, logs, or responses.

• The project file MCP only allows reading PNG, JPEG, and WebP files within CLAUDE_PROJECT_DIR.

• The transparent gateway listens only on 127.0.0.1 by default.

• Text recognized in images should always be treated as untrusted data and cannot override user or system instructions.

• If gateway preprocessing fails, a clear error is returned; the DS request is not silently made without the image information.

Update and Uninstall

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

Uninstall:

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

Uninstall the Windows persistent gateway and restore the original upstream:

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

The uninstaller will not delete the DASHSCOPE_API_KEY and will not stop unknown programs occupying the same port. The temporary CLI launcher does not modify permanent configurations; exiting the Claude Code it started will stop the gateway.

References

• Claude Code MCP

• Claude Code Hooks

• Claude Code Plugin Marketplace

• Alibaba Cloud Bailian Visual Understanding

License

MIT