mcp-plus: Claude Code Qwen Vision

Claude Code가 DeepSeek 등 텍스트 전용 모델을 사용할 때도 무감각하게 이미지 이해 능력을 얻을 수 있도록 합니다.

기본 시각 모델: 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를 호출할 수 있는 Bailian 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

구성 항목

보안 설명

• 이미지는 Alibaba Cloud Bailian으로 전송됩니다. 전송 전에 프로덕션 자격 증명, 개인 정보 및 민감한 데이터를 제거해야 합니다.

• 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

• Alibaba Cloud Bailian 시각 이해

License

MIT