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. Подходит для 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), три визуальных инструмента автоматически скрываются, чтобы избежать лишнего делегирования; они отображаются только для чисто текстовых основных моделей.

Конфигурация

Приоритет: 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 (выбрать одно из четырёх).

• vision_ocr — посимвольное извлечение текста с изображения. Параметры те же, что у analyze (без prompt).

• vision_analyze_batch — пакетный анализ нескольких изображений. Параметры: items (обязательно, каждый элемент — один из четырёх источников изображения, может содержать prompt), prompt (необязательно), concurrency (по умолчанию 3, диапазон 1-8).

Открытый исходный код

Распространяется в виде исходного кода. Приветствуются Fork / Issue / PR.