image-recognition-mcp

MCP-сервер распознавания изображений на основе локального фреймворка Vision в macOS — позволяет AI-моделям без зрения «видеть» скриншоты и изображения.

Предоставляет 4 MCP-инструмента для AI-клиентов (opencode / Claude Desktop / Cursor / Cline и др.):
OCR-распознавание текста / классификация объекта изображения / комплексное распознавание / скриншот и распознавание. Весь вывод выполняется локально, данные не покидают устройство.

Содержание

• Возможности

• Архитектура

• Быстрый старт

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

• Форматы ввода и вывода

• Механизм запуска

• Настройка подключения клиентов

• Производительность и ресурсы

• Права и конфиденциальность

• Поиск и устранение неисправностей

• Рекомендации по расширению

Related MCP server: npu-vision-fallback

Возможности

• 100% локальный вывод: на основе Apple Vision (VNRecognizeTextRequest + VNClassifyImageRequest), ноль сетевых запросов, ноль внешних API-вызовов.

• OCR для смешанного китайско-английского текста: поддержка китайского (zh-Hans), английского и 20+ языков, включая распознавание рукописного текста, с выбором уровня точности (accurate / fast).

• Классификация объекта/сцены изображения: возвращает метки категорий и уверенность, на основе которых модель может генерировать описание на естественном языке.

• Три источника изображений: локальный путь, data:image/png;base64,... URI, чистый base64 (проверка сигнатуры PNG).

• Автоматическое уменьшение больших изображений: изображения больше 4096px по умолчанию автоматически уменьшаются перед распознаванием — быстрее и экономнее по памяти.

• Структурированный JSON-вывод: все инструменты возвращают единый JSON {status, ...}, содержащий уверенность и нормализованные ограничивающие рамки, что упрощает разбор и использование моделью.

• Опциональный скриншот: прямой вызов команды screencapture для снятия и распознавания экрана (требуется разрешение на запись экрана).

Архитектура

┌────────────────────────────────────────────────────────────┐
│  AI 会话客户端（opencode / Claude Desktop / Cursor / ...）   │
│  无视觉模型看到图片路径 → 调用工具                            │
└──────────────────────────┬─────────────────────────────────┘
                           │  MCP 协议 (stdio JSON-RPC)
┌──────────────────────────▼─────────────────────────────────┐
│  image-recognition MCP 服务器 (Python + MCPServer)          │
│  ┌──────────────┬──────────────┬──────────────┐            │
│  │  ocr_image   │recognize_image│describe_image│            │
│  │screenshot_…  │              │              │            │
│  └──────────────┴──────────────┴──────────────┘            │
└──────────────────────────┬─────────────────────────────────┘
                           │  Vision 框架调用 (pyobjc)
┌──────────────────────────▼─────────────────────────────────┐
│  macOS 本地视觉引擎                                          │
│  VNRecognizeTextRequest   —— OCR（中英+多语言）              │
│  VNClassifyImageRequest   —— 图像主体/场景分类                │
│  全程本机推理，无网络请求，数据不出设备                        │
└────────────────────────────────────────────────────────────┘

Быстрый старт

Требования к окружению

• macOS 13+ (рекомендуется 14+ — Vision лучше всего распознаёт китайский)

• Python 3.10+ (протестировано на 3.13.12)

• Установлены Xcode Command Line Tools (xcode-select --install)

Установка

# 克隆/进入项目目录
cd /path/to/image-recognition-mcp

# 创建 venv 并安装依赖
python3 -m venv .venv
source .venv/bin/activate
pip install -U pip
pip install -r requirements.txt

Самопроверка

# 生成一张含中英文的测试图片
.venv/bin/python scripts/make_test_image.py

# 直接测试 Vision 引擎（不走 MCP）
.venv/bin/python scripts/test_engine.py sample/test_card.png

# 端到端测试 MCP 服务器（启动 stdio，列出工具，调用 OCR）
.venv/bin/python scripts/test_mcp.py sample/test_card.png

Ожидаемый результат: 3 строки текста (MacBook Air 图片识别测试 / Hello Vision OCR 12345 / 日期：2026-08-04 13:30) распознаются полностью, а результат классификации изображения разумен (document/printed_page/screenshot и т.п.).

Прямой вызов движка из командной строки (опционально)

# OCR
.venv/bin/python vision_engine.py /path/to/image.png --mode ocr

# 主体分类
.venv/bin/python vision_engine.py /path/to/image.png --mode classify

# 综合识别
.venv/bin/python vision_engine.py /path/to/image.png --mode analyze

# 截屏到 ~/Pictures
.venv/bin/python vision_engine.py --mode shot

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

После запуска сервер предоставляет клиентам 4 инструмента:

1. ocr_image — извлечение текста из изображения (OCR)

{
  "image": "/Users/me/Pictures/shot.png",      // 必填，路径 / data URI / 纯 base64
  "languages": "zh-Hans,en-US",                // 可选，逗号分隔，顺序即优先级
  "min_confidence": 0.2,                       // 可选，0~1，过滤低置信度结果
  "filter_noise": true                         // 可选，默认 true，过滤图标/符号误识噪声
}

Пояснение по filter_noise: автоматически отфильтровывает шум ошибочного распознавания иконок на скриншотах (например, •••, ③, одиночные 8/凸 и т.п.), но сохраняет числовые строки, которые могут иметь бизнес-смысл (суммы, номера карт, коды транзакций, время и т.д.). Отфильтрованные строки помещаются отдельно в поле noise в ответе, информация не теряется; если нужен полный исходный результат, установите filter_noise: false.

Возвращает:

{
  "status": "ok",
  "image": "/Users/me/Pictures/shot.png",
  "text": "完整拼接的全文",
  "count": 3,
  "lines": [
    {
      "text": "MacBook Air 图片识别测试",
      "confidence": 0.5,
      "bbox": {"x": 0.052, "y": 0.695, "width": 0.555, "height": 0.133}
    }
  ]
}

2. recognize_image — комплексное распознавание

{
  "image": "/path/to/img.png",
  "languages": "zh-Hans,en-US"
}

Возвращает:

{
  "status": "ok",
  "image": "/path/to/img.png",
  "info": {"path": "...", "size_bytes": 12345, "pixel_width": 1200, "pixel_height": 420, "uti": "public.png"},
  "ocr": [...],
  "classification": [{"label": "document", "confidence": 0.529}, ...],
  "summary": "图中文字(OCR):\n... \n图像主体/场景: document(0.53)",
  "elapsed_ms": 98
}

3. describe_image — классификация объекта/сцены

{
  "image": "/path/to/img.png",
  "top_k": 8,                    // 1~20
  "min_confidence": 0.05
}

Возвращает:

{
  "status": "ok",
  "image": "/path/to/img.png",
  "labels": [
    {"label": "Animal", "confidence": 0.812},
    {"label": "Cat", "confidence": 0.703}
  ]
}

label — на английском (например, Animal / Landscape / Food / Vehicle); вызывающая модель сама интерпретирует и переводит его.

4. screenshot_and_recognize — скриншот и распознавание

{
  "languages": "zh-Hans,en-US"
}

Снимает весь экран → OCR. Требуется разрешение на запись экрана, см. Права и конфиденциальность.

Форматы ввода и вывода

Формат ввода (параметр image)

Проверено на практике: скриншот рабочего стола 256KB → base64 data URI (около 340 тыс. символов) → вызов MCP-инструмента, распознано 42 строки полезного текста + 4 строки шума, время ~0.6s, результат совпадает с передачей пути напрямую.

Сервер автоматически:

• проверяет существование пути

• декодирует data URI / base64 и записывает во временный файл

• проверяет поддержку формата (на основе CGImageSource, совместим с JPEG/PNG/HEIC/TIFF/GIF/BMP/WebP)

Формат вывода

• Все инструменты возвращают строку (JSON), чтобы модель могла напрямую разобрать её.

• Успех: {"status": "ok", ...}

• Ошибка: {"status": "error", "error": "..."}

• Координаты ограничивающей рамки (bbox) нормализованы (начало координат в левом нижнем углу, 0~1), как в Vision.

Механизм запуска

MCP использует протокол, в котором «инструменты вызываются моделью по мере необходимости»; сервер не может сам узнать, что пользователь загрузил изображение. Для «автоматического запуска» требуется содействие со стороны клиента/модели:

Пути запуска

Рекомендуемая договорённость в промпте (ключевой момент)

Чтобы гарантировать 100% запуск, добавьте в AGENTS.md в корне проекта или в системный промпт модели:

## 图片处理约定

当用户消息中出现图片路径或 base64 data URI 时：
- 若当前模型具备视觉能力 → 直接读取图片（不要调用本 MCP 服务器）。
- 若当前模型不具备视觉能力 → **必须**调用 `image-recognition` MCP 服务器的 `ocr_image` 或
  `recognize_image` 工具，将识别结果作为图片内容继续处理。
- 工具调用结果已经包含识别出的文字与图像描述，无需再要求用户提供说明。

После добавления этой договорённости в AGENTS.md такие клиенты, как opencode / Claude Desktop, отправят эту инструкцию модели вместе с системным промптом, обеспечив настоящий «автоматический запуск».

Настройка подключения клиентов

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

opencode

Запишите в opencode.json (уровень проекта) или ~/.config/opencode/opencode.json (уровень пользователя):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "image-recognition": {
      "type": "local",
      "command": [
        "/path/to/image-recognition-mcp/.venv/bin/python",
        "/path/to/image-recognition-mcp/mcp_server.py"
      ],
      "enabled": true
    }
  }
}

Перезапустите opencode — в списке инструментов появятся 4 инструмента image-recognition.

Claude Desktop

Запишите в ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "image-recognition": {
      "command": "/path/to/image-recognition-mcp/.venv/bin/python",
      "args": ["/path/to/image-recognition-mcp/mcp_server.py"]
    }
  }
}

Cursor / Cline / универсальные stdio MCP-клиенты

{
  "mcpServers": {
    "image-recognition": {
      "command": "/path/to/image-recognition-mcp/.venv/bin/python",
      "args": ["/path/to/image-recognition-mcp/mcp_server.py"]
    }
  }
}

WorkBuddy

Отредактируйте ~/.workbuddy/mcp.json, добавьте image-recognition в mcpServers; изменения вступят в силу после перезапуска:

WorkBuddy

Примеры конфигураций см. в каталоге configs/:

• configs/opencode.example.json

• configs/claude-desktop.example.json

• configs/generic-stdio.example.json

Производительность и ресурсы

Рекомендации по оптимизации:

• В _load_cg_image уже встроено автоматическое уменьшение до 4096px, этого достаточно для подавляющего большинства скриншотов.

• При массовом распознавании изображений можно объединить несколько вызовов ocr_image в один recognize_image на стороне клиента, чтобы уменьшить расход токенов контекста.

• Выбор level="fast" в OCR ускоряет работу на 30–50% ценой небольшого снижения точности (мелкий текст, рукописный ввод).

Права и конфиденциальность

• Полностью локально: всё распознавание выполняется в рамках macOS Vision, данные вообще не покидают устройство, не нужны никакие API-ключи или сеть.

• Разрешение на запись экрана (нужно только для инструмента screenshot_and_recognize):

  • При первом вызове macOS покажет запрос или потребует авторизацию в «Системные настройки > Конфиденциальность и безопасность > Запись экрана».

  • Предоставьте разрешение хост-процессу, запускающему MCP-сервер (например, терминалу, Claude Desktop, opencode).

  • Без разрешения инструмент вернёт понятное сообщение об ошибке, а не будет молча падать.

Поиск и устранение неисправностей

Рекомендации по расширению

Чтобы добавить больше возможностей Vision, можно по аналогии с существующими функциями в vision_engine.py добавить соответствующие Vision-запросы, например:

• VNDetectFaceRectanglesRequest — обнаружение лиц

• VNGenerateAttentionBasedSaliencyImageRequest — области значимости (saliency)

• VNDetectDocumentSegmentationRequest — сегментация областей документа (для сканирующих приложений)

• VNRecognizeAnimalsRequest — распознавание пород животных (iOS 15+, macOS 12+)

После реализации достаточно добавить в mcp_server.py новый @mcp.tool(), чтобы инструмент стал доступен модели.

Структура файлов

image-recognition-mcp/
├── README.md                       # 本文档
├── requirements.txt                # Python 依赖
├── vision_engine.py                # Vision 框架封装（OCR + 分类 + 截图）
├── mcp_server.py                   # MCP 服务器主程序
├── scripts/
│   ├── make_test_image.py          # 生成含中英文的测试图片
│   ├── test_engine.py              # Vision 引擎自测
│   └── test_mcp.py                 # MCP 服务器端到端冒烟测试
├── configs/                        # 客户端配置示例
│   ├── opencode.example.json
│   ├── claude-desktop.example.json
│   └── generic-stdio.example.json
├── sample/
│   └── test_card.png               # 测试图片（含中文/英文/数字/红色圆形）
└── .venv/                          # Python 虚拟环境（运行后生成）

Лицензия

Код проекта распространяется по лицензии MIT. Вызовы Vision framework регулируются лицензией Apple SDK; работает только на macOS.