vision-mcp

テキストのみのメインモデルに視覚能力を補完する軽量MCPサーバー。メインモデルが画像（スクリーンショット、UI図、フローチャート、エラー画面のスクリーンショットなど）に遭遇したが理解できない場合、MCPツールを通じて画像をOpenAI互換のマルチモーダルバックエンド（Qwen-VL、GPT-4o、Gemini、ローカルvLLMなど）に渡して分析し、テキスト結果を返します。

主模型(纯文本) ──调用 MCP 工具──▶ vision-mcp ──Chat Completions──▶ 多模态模型
   Claude/Codex ◀──────文本结果───────◀──────────────────────────   Qwen-VL / GPT-4o / ...

クイックスタート

推奨：リポジトリに同梱の bin/wrapper.sh で直接起動します。wrapperは初回呼び出し時に自動でディレクトリ内に .venv を作成し依存関係をインストールします（uv優先、uvがない場合はvenv+pip）。手動インストールは不要です。その後、実際の server.py をexecします。macOS / Linuxに対応。

# 方式一（推荐，免手动装依赖）：MCP client 指向 wrapper 即可
claude mcp add vision-mcp -- /绝对/路径/vision-mcp/bin/wrapper.sh

# 或先自测：wrapper 会自举依赖并启动 server
/绝对/路径/vision-mcp/bin/wrapper.sh --check

Windowsの場合は python -m venv + install.ps1 を使用するか、直接 python server.py を実行してください。

Related MCP server: vision-mcp

インストール（ソースからの構築）

まずMCPサーバー本体（Python）をインストールします：

# Windows
powershell -ExecutionPolicy Bypass -File .\install.ps1
# macOS / Linux
./install.sh

次に、お使いのクライアントに応じて接続します：

Claude Code

claude mcp add vision-mcp -- \
  python /绝对/路径/vision-mcp/server.py

Codex

codex mcp add vision-mcp -- \
  python /绝对/路径/vision-mcp/server.py

MCP設定を変更した後は、クライアントの再起動が必要です。

pi

cp pi-extensions/vision-mcp.ts ~/.pi/agent/extensions/
# 依赖：typebox（必需，工具参数模式定义）；sharp（可选，图片缩放，未装则自动降级为不缩放）
cd ~/.pi/agent/extensions && npm i sharp typebox

コピー後、piを再起動するか /reload で自動的に読み込まれます。pi install は不要です。pi拡張は機能ゲーティングをサポート：メインモデルがネイティブに画像をサポートしている場合（input に image を含む）、不要な委任を避けるため3つの視覚ツールを自動的に非表示にし、テキストのみのメインモデルでのみ表示します。

設定

優先順位：config.json > プロセス環境変数 > .env > デフォルト値。config.json はgitignoreされており、リポジトリには含まれません。

cp config.example.json config.json   # 再编辑 api_key 等字段

{
  "api": "openai-completions",
  "api_key": "sk-your-dashscope-api-key",
  "base_url": "https://dashscope.aliyuncs.com/compatible-mode/v1",
  "model": "qwen-vl-plus",
  "max_tokens": 4096,
  "timeout": 120,
  "max_retries": 2,
  "retry_backoff": 2
}

pi拡張は追加で ~/.pi/vision-mcp/config.json を読み取ります（または VISION_CONFIG_PATH で指定）。キーは上記と同じです。

対応形式：PNG / JPEG / WebP / GIF（BMPは主要な視覚バックエンドがサポートしていないため除外）。

一般的なバックエンド：DashScope（デフォルト）VISION_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1；OpenAI model=gpt-4o；ローカルvLLM base_url=http://localhost:8000/v1。

設定の確認

# wrapper 方式（依赖未装则先自举）
./bin/wrapper.sh --check
# 源码自建（依赖手动安装后）
python server.py --check   # 打印生效配置，API key 脱敏

ツール

• vision_analyze — 汎用画像理解。パラメータ：prompt（任意）、image/image_path/image_url/image_base64（4つのうちいずれか1つ）。

• vision_ocr — 画像内のテキストを一字一句抽出。パラメータはanalyzeと同じ（promptなし）。

• vision_analyze_batch — 複数画像の一括分析。パラメータ：items（必須、各項目は4つのうちいずれかの画像ソース、prompt を付けることも可能）、prompt（任意）、concurrency（デフォルト3、範囲1-8）。

オープンソース

ソースコード形式でオープンソース化しています。Fork / Issue / PR 歓迎です。