mimo-vision-mcp

Дайте текстовым LLM возможность видеть через MCP, используя визуальные модели, такие как Xiaomi MiMo-V2.5.

Через MCP (Model Context Protocol) возможности понимания изображений визуальных моделей (например, Xiaomi MiMo-V2.5) предоставляются текстовым LLM без мультимодальных возможностей. Когда текстовая модель сталкивается с изображением/скриншотом/путём к изображению, она может активно вызывать инструменты analyze_image, describe_image, extract_text_from_image и получать визуальные возможности.

🚀 Быстрый запуск в один клик (новичок освоится за 1 минуту, без ввода команд)

В проект встроен WebUI запуск в один клик — всё управление мышью, все настройки окружения выполняются автоматически, без командной строки:

1. Скачайте / клонируйте проект локально

2. Дважды щёлкните start-webui.bat (Windows) — скрипт автоматически создаст .env (из .env.example), установит окружение/зависимости, запустит сервис и автоматически откроет браузер

3. После открытия браузера введите свой API Key → нажмите «Применить к CLI», или просто перетащите изображение в окно → выберите визуальную модель → нажмите «Предварительный просмотр», и вы увидите, как визуальная модель «описывает изображение»

При первом запуске автоматически установятся зависимости (требуется интернет, около 1–2 минут), после этого двойной щелчок открывает мгновенно. Совершенно не нужно знать Python, не нужно вручную вводить pip, не нужно вручную создавать .env — скрипт всё делает автоматически.

Полное подключение визуальных возможностей для текстовых LLM в командной строке см. ниже подключение к opencode.

Related MCP server: mimo-vision-mcp

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

Текстовая модель отвечает за «планирование», визуальная модель — за «просмотр», MCP — это интерфейс, соединяющий их — данные изображения не проходят через текстовую модель.

用户给图片路径/URL
  → ① 文本 LLM 根据工具列表 + 调用指引，决定调用 analyze_image
  → ② opencode / 任意 MCP 客户端（stdio）
  → ③ mimo-vision MCP server（图片归一化 + 转发请求）
  → ④ 视觉模型（MiMo-V2.5 等，经 OpenCode Go / 自定义供应商）真正"看"图
  → ⑤ 文本结果原路返回，文本模型转述给用户

Возможности

• Запуск в один клик: дважды щёлкните start-webui.bat — автоматическая установка зависимостей, запуск сервиса, открытие браузера, новичкам без порога входа

• Готово к использованию: по умолчанию подключён OpenCode Go, достаточно ввести API Key, можно также переключиться на официальный Xiaomi / любого пользовательского провайдера

• На основе OpenAI-совместимого протокола, локальная передача через stdio, можно подключить opencode / Claude Desktop / Cursor и любой MCP-клиент

• Гибкий ввод изображений: локальный путь / http(s) URL / base64 data URI / чистый base64

• Поддержка нескольких изображений, автоматическое определение формата (JPEG/PNG/GIF/WebP/BMP), проверка лимита 50MB

• Автоматический выбор API-протокола в зависимости от модели: gpt-*/grok-* используют Responses API, остальные — chat/completions (можно принудительно указать)

• Встроенная WebUI панель конфигурации: визуальный выбор модели, предварительный просмотр, выбор синхронизируется с CLI, без перезапуска

• Без API key возвращается дружелюбное сообщение об ошибке, без сбоев

Структура каталога

mimo-vision-mcp/
├── mimo_vision_mcp/
│   ├── config.py           # 配置读取（.env 实时重读）+ 应用到 MCP
│   ├── image_loader.py     # 图片输入归一化 + MIME 探测
│   ├── providers.py        # 供应商注册表 + call_vision（chat/responses 适配）
│   └── server.py           # FastMCP server + 3 个工具
├── webui/                  # WebUI 配置面板（FastAPI + 单页 HTML）
├── tests/                  # 单元测试
├── .github/workflows/ci.yml
├── opencode.example.json   # opencode 接入配置示例
├── AGENTS.md               # 文本模型的调用指引
├── start-webui.bat           # 🚀 一键启动（Windows，双击即用）
├── LICENSE
└── pyproject.toml

Установка

python -m venv .venv
# Windows: .\.venv\Scripts\python.exe -m pip install -e ".[dev]"
.venv/bin/python -m pip install -e ".[dev]"

Настройка API Key

Проект по умолчанию использует OpenCode Go для вызова MiMo-V2.5 (модель mimo-v2.5, OpenAI-совместимая конечная точка https://opencode.ai/zen/go/v1).

1. Подпишитесь на Go на opencode.ai/auth, скопируйте API Key

2. Скопируйте .env.example в .env и заполните:

   MIMO_API_KEY=你的-opencode-go-key

Также можно переопределить через переменные окружения (config.py перечитывает .env при каждом вызове):

Смена визуальной модели: в OpenCode Go более быстрые мультимодальные модели можно указать MIMO_MODEL как gpt-5.6-luna (через /responses) или minimax-m3. Обратите внимание: mimo-v2.5-pro — чисто текстовая модель, не может видеть изображения.

Запуск MCP server

# 方式一：控制台脚本
mimo-vision-mcp
# 方式二：模块运行
python -m mimo_vision_mcp.server

Подключение к opencode

См. opencode.example.json, зарегистрируйте mimo-vision как локальный stdio MCP server:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "mimo-vision": {
      "type": "local",
      "command": ["<你的python路径>", "-m", "mimo_vision_mcp.server"],
      "enabled": true,
      "environment": { "MIMO_API_KEY": "{env:MIMO_API_KEY}" }
    }
  },
  "experimental": { "mcp_timeout": 120000 }
}

Примечание: experimental.mcp_timeout (по умолчанию 30s) контролирует таймаут вызова инструментов MCP. Визуальные запросы могут занимать десятки секунд, нужно установить более 120s; не устанавливайте timeout отдельно в mcp.mimo-vision, это переопределит mcp_timeout и приведёт к таймауту. После изменения конфигурации необходимо перезапустить opencode.

Проект также включает AGENTS.md (инструкции для текстовой модели), можно добавить через глобальную конфигурацию "instructions": ["<путь>/AGENTS.md"] в каждую сессию, чтобы текстовая модель при встрече с изображением активно вызывала инструменты.

Описание инструментов

Каждый элемент images поддерживает:

• Локальный абсолютный путь: C:/Users/xx/Pictures/a.png

• Публичный URL: https://example.com/a.jpg

• base64 data URI: data:image/png;base64,....

• Чистую base64 строку

Возвращает JSON: { "result": "...", "error": "", "model": "...", "usage": {...} }

WebUI (интерактивный интерфейс · запуск в один клик)

Рекомендуемый вход для новичков: графический интерфейс, загрузка изображений, выбор модели, просмотр результата — всё мышью.

Запуск в один клик (самый простой, без команд)

Дважды щёлкните start-webui.bat (Windows):

1. Скрипт автоматически проверит/создаст окружение, установит зависимости

2. Автоматически запустит сервис и автоматически откроет браузер

3. Если сервис уже запущен, просто откроет браузер, без повторного запуска

Для не-Windows пользователей ручной запуск: python -m pip install -e ".[web]" && python -m webui.app, затем откройте http://127.0.0.1:8000 (порт можно изменить через MIMO_WEBUI_PORT).

Функции интерфейса

• Вверху «CLI / MCP текущая активная модель» показывает провайдера/модель/стиль, которые реально использует командная строка LLM

• После выбора модели нажмите «Применить к CLI (синхронизировать с MCP)», конфигурация записывается в .env, без перезапуска, CLI при следующем вызове использует новую модель

• Внизу «Предварительный просмотр (не влияет на CLI)» для тестирования эффекта

• API Key хранится в localStorage браузера; при «Применить к CLI» можно также записать в .env

Тестирование

python -m pytest -q

Частые вопросы

• Я не умею программировать / не хочу вводить команды?: Дважды щёлкните start-webui.bat, скрипт автоматически создаст .env, установит зависимости, запустит сервис, откроет браузер — всё мышью

• Где ввести API Key?: После клонирования нет .env (в репозитории только пустой шаблон .env.example). Двойной запуск скрипта автоматически создаст .env, затем введите Key в веб-интерфейсе и нажмите «Применить к CLI», или отредактируйте MIMO_API_KEY в .env

• Возвращается «API Key не настроен»: настройте MIMO_API_KEY в .env (или введите в WebUI и нажмите «Применить к CLI»)

• Формат изображения не поддерживается: поддерживаются только JPEG/PNG/GIF/WebP/BMP

• Ошибка «не удаётся разобрать» при вводе base64: убедитесь, что ввод — корректный base64 и формат в поддерживаемом диапазоне

• Таймаут вызова инструмента MCP: увеличьте experimental.mcp_timeout до 120000ms и более

Лицензия

MIT

Ссылки

• Документация OpenCode Go

• Документация Xiaomi MiMo API

• Руководство по пониманию изображений