mcp-plus：Claude Code Qwen Vision

DeepSeek などのテキスト専用モデルを使用する Claude Code に、画像認識能力を違和感なく追加します。

デフォルトのビジョンモデル：qwen3.8-max デフォルトの Qwen アドレス：https://dashscope.aliyuncs.com/compatible-mode/v1

プロジェクトは 2 つのパスを提供します。

1. 透過ゲートウェイ（推奨）：ユーザーが通常通り画像を貼り付けると、ゲートウェイが自動的に画像を Qwen に渡し、構造化されたビジョン結果を DS に渡します。実行中にコマンドを入力する必要はなく、DS が能動的にツールを呼び出す必要もありません。

2. Claude Code MCP プラグイン：analyze_image ツールと明示的なスキルを提供し、プロジェクト内の画像ファイルを直接読み取る場合や予備手段として適しています。

なぜ透過ゲートウェイが必要か

Claude Code の UserPromptSubmit フックは現在テキスト prompt のみを提供し、貼り付けた画像の元の Base64 や一時パスをフックに提供しません。また、フックはセッション中にユーザーが切り替えたモデルを確実に認識できません。そのため、スキル、フック、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 キー

• 設定済みの DS/Claude Anthropic 互換インターフェース

リポジトリをクローン：

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

まず Qwen キーを 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 キーはコピーまたは書き込みしません。

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 キーを設定：

$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 を返せない場合は、決定論的な予備スキルを使用します。

/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

設定項目

セキュリティに関する注意

• 画像は Alibaba Cloud 百煉に送信されます。送信前に、本番環境の資格情報、個人情報、機密データを削除してください。

• API キーは環境変数からのみ読み取られ、プラグイン、ログ、レスポンスには書き込まれません。

• プロジェクトファイル 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

• Alibaba Cloud 百煉ビジョン理解

ライセンス

MIT