Vision MCP

Позволяет LLM без визуальных возможностей (например, GLM) обрабатывать изображения в Claude Code / Codex.

Принцип работы

Когда основная модель сталкивается с изображением, она вызывает инструмент describe_image, предоставляемый этим MCP:

1. Инструмент читает локальный файл изображения

2. Вызывает настроенную вами визуальную модель (Qwen-VL / GPT-4o / GLM-4V / Doubao или любой другой OpenAI-совместимый интерфейс)

3. Возвращает текстовое описание основной модели

4. Основная модель продолжает рассуждения на основе текста

Основная модель никогда не касается бинарных данных изображения, поэтому даже чисто текстовые модели могут это использовать.

Проект не имеет сторонних зависимостей (чистая стандартная библиотека Python), работает на Python 3.8+ без установки через pip.

Related MCP server: Image-Vision MCP Server

Установка одной командой

git clone https://github.com/Ruiba0/Vision-MCP.git
cd vision-mcp
python3 install.py

В Windows нет команды python3, используйте python install.py; то же самое относится ко всем python3 ниже.

Скрипт установки интерактивно выполнит:

• Позволит вам ввести base URL / имя модели / API key визуальной модели (с справочником распространённых поставщиков)

• Зарегистрирует MCP в Claude Code (claude mcp add)

• Зарегистрирует MCP в Codex (запись в ~/.codex/config.toml)

• Добавит правила обработки изображений в ~/.claude/CLAUDE.md и ~/.codex/AGENTS.md

Скрипт идемпотентен, его можно запускать повторно.

Ручная установка

Если вы не хотите использовать скрипт установки:

1. Настройте визуальную модель

   Скопируйте config.example.json в config.json и заполните конфигурацию вашей визуальной модели:

   {
     "vision_api_base": "https://dashscope.aliyuncs.com/compatible-mode/v1",
     "vision_model": "qwen-vl-max",
     "vision_api_key": "sk-你的key",
     "max_image_bytes": 10485760
   }

2. Зарегистрируйте в Claude Code

   claude mcp add --scope user vision -- python3 /绝对路径/server.py

   Добавьте --scope user, чтобы сделать его глобально доступным (без этого он будет действовать только в текущем каталоге).

3. Зарегистрируйте в Codex

   Отредактируйте ~/.codex/config.toml, добавив:

   [mcp_servers.vision]
   command = "python3"
   args = ["/绝对路径/server.py"]

4. Добавьте правила обработки изображений

   Добавьте следующее содержимое в ~/.claude/CLAUDE.md и ~/.codex/AGENTS.md (чтобы основная модель активно вызывала инструмент при встрече с изображением):

   ## 图片处理
   
   当用户提到图片文件路径（.png/.jpg/.jpeg/.gif/.webp/.bmp），或要求查看/分析/识别某个图片文件时：
   
   - 先判断当前主模型自身是否具备视觉能力
   - 具备视觉（如 Claude Sonnet/Opus、GPT-4o、Qwen-VL 等多模态模型）→ 直接读取图片并分析
   - 不具备视觉（如 GLM 等纯文本模型）→ 调用 vision MCP 的 describe_image 工具，传入图片路径和问题
   - 不确定自身是否支持视觉时，默认调用 describe_image 工具作为兜底
   - 用户明确要求"用 MCP 看"或"调视觉模型"时，无论主模型是否支持视觉，都调用 describe_image 工具

Поддерживаемые визуальные модели

Любая визуальная модель, совместимая с протоколом OpenAI, может быть использована:

Если вам нужно использовать нативный протокол Anthropic (например, Claude), вам придётся самостоятельно изменить vision_client.py; в настоящее время поддерживается только протокол, совместимый с OpenAI.

Использование

После установки перезапустите Claude Code / Codex и в диалоге:

• "Посмотри на это изображение в ~/Desktop/diagram.png"

• "Проанализируй ошибку в ~/Screenshots/error.jpg"

• "Распознай весь текст в ~/Documents/notes/page1.jpeg"

(В Windows пути выглядят как D:/temp/diagram.png, пишите в соответствии с вашей системой)

Основная модель автоматически вызовет инструмент describe_image, инструмент вернёт текстовое описание визуальной модели, и основная модель продолжит отвечать на основе описания.

Параметры инструмента

describe_image(path: str, question: str = "详细描述这张图片的内容") -> str

• path: абсолютный путь к файлу изображения, поддерживаются png/jpg/jpeg/gif/webp/bmp

• question: вопрос к визуальной модели, можно настраивать по сценарию ("распознать текст", "описать макет", "проанализировать диаграмму" и т.д.)

Структура проекта

vision-mcp/
├── server.py              # MCP 服务（内置 stdio JSON-RPC 实现，无 SDK 依赖）
├── vision_client.py       # 视觉模型调用（OpenAI 兼容协议，urllib 实现）
├── config.example.json    # 配置模板（提交到 git）
├── config.json            # 你的实际配置（gitignored）
├── install.py             # 一键安装脚本
└── README.md

Часто задаваемые вопросы

В: При вызове появляется ошибка 视觉模型连接失败 Проверьте, правильный ли путь vision_api_base. Инструмент добавляет /chat/completions после base URL, поэтому base URL не должен содержать суффикс /chat/completions.

В: При вызове появляется ошибка HTTP 401 API key недействителен или нет разрешения на эту модель, проверьте, соответствуют ли vision_api_key и vision_model соответствующей платформе.

В: Основная модель не вызывает инструмент автоматически Убедитесь, что правила обработки изображений в CLAUDE.md / AGENTS.md добавлены. Ключевые слова в правилах (изображение, просмотр, анализ) направят основную модель на вызов describe_image.

В: Хочу сменить визуальную модель Отредактируйте три поля в config.json, код менять не нужно. Или перезапустите python3 install.py для повторной настройки.

Зависимости

• Python 3.8+ (чистая стандартная библиотека, не нужно устанавливать пакеты через pip)

Лицензия

MIT