image-recognition-mcp

Servidor MCP de reconocimiento de imágenes basado en el framework Vision local de macOS — permite que los modelos de IA sin visión también puedan «ver» capturas de pantalla e imágenes.

Proporciona 4 herramientas MCP para clientes de IA (opencode / Claude Desktop / Cursor / Cline, etc.):
Reconocimiento de texto OCR / Clasificación del sujeto de la imagen / Reconocimiento integral / Captura de pantalla y reconocimiento. Inferencia totalmente local; los datos no salen del equipo.

Índice

• Características

• Arquitectura

• Inicio rápido

• Descripción de las herramientas MCP

• Formatos de entrada y salida

• Explicación del mecanismo de activación

• Configuración de integración del cliente

• Rendimiento y recursos

• Permisos y privacidad

• Solución de problemas

• Sugerencias de ampliación

Related MCP server: npu-vision-fallback

Características

• Inferencia 100 % local: basado en el framework Apple Vision (VNRecognizeTextRequest + VNClassifyImageRequest), cero solicitudes de red, cero llamadas a API externas.

• OCR mixto chino-inglés: admite chino (zh-Hans), inglés y más de 20 idiomas, incluido el reconocimiento de escritura a mano, con niveles de precisión opcionales (accurate / fast).

• Clasificación del sujeto/escena de la imagen: devuelve etiquetas de categoría y confianza; el modelo puede generar descripciones en lenguaje natural a partir de ellas.

• Tres fuentes de imagen: ruta local, URI data:image/png;base64,..., base64 puro (validación del número mágico PNG).

• Miniatura automática para imágenes muy grandes: las imágenes de más de 4096 px se reducen automáticamente a una miniatura antes del reconocimiento; más rápido y con menos memoria.

• Salida JSON estructurada: todas las herramientas devuelven un JSON unificado {status, ...} con confianza y cuadro delimitador normalizado, fácil de analizar y citar para el modelo.

• Captura de pantalla opcional: llama directamente al comando screencapture para capturar y reconocer (requiere permiso de grabación de pantalla).

Arquitectura

┌────────────────────────────────────────────────────────────┐
│  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   —— 图像主体/场景分类                │
│  全程本机推理，无网络请求，数据不出设备                        │
└────────────────────────────────────────────────────────────┘

Inicio rápido

Requisitos del entorno

• macOS 13+ (se recomienda 14+, el framework Vision ofrece los mejores resultados de reconocimiento de chino)

• Python 3.10+ (probado con 3.13.12)

• Xcode Command Line Tools instalado (xcode-select --install)

Instalación

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

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

Autocomprobación

# 生成一张含中英文的测试图片
.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

Salida esperada: 3 líneas de texto (MacBook Air 图片识别测试 / Hello Vision OCR 12345 / 日期：2026-08-04 13:30) reconocidas por completo, y un resultado de clasificación de imagen razonable (document/printed_page/screenshot, etc.).

Llamada directa al motor desde la línea de comandos (opcional)

# 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

Descripción de las herramientas MCP

Tras el inicio, el servidor expone 4 herramientas al cliente:

1. ocr_image — extrae el texto de la imagen (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，过滤图标/符号误识噪声
}

Nota sobre filter_noise: filtra automáticamente el ruido de reconocimiento erróneo de iconos en capturas de pantalla (como •••, ③, un 8/凸 suelto, etc.), pero conserva las cadenas numéricas que puedan tener significado comercial (importes, números de tarjeta, identificadores de transacción, horas, etc.). Las líneas filtradas se colocan por separado en el campo noise de la respuesta, sin pérdida de información; si necesitas el resultado completo original, establece filter_noise: false.

Devuelve:

{
  "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 — reconocimiento integral

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

Devuelve:

{
  "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 — clasificación del sujeto/escena

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

Devuelve:

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

label está en inglés (p. ej., Animal / Landscape / Food / Vehicle); el modelo que realiza la llamada lo interpreta y traduce por sí mismo.

4. screenshot_and_recognize — captura de pantalla y reconocimiento

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

Captura toda la pantalla → OCR. Requiere permiso de grabación de pantalla; consulta Permisos y privacidad.

Formatos de entrada y salida

Formato de entrada (parámetro image)

Prueba real: captura de pantalla de escritorio de 256 KB → data URI base64 (unas 340 000 caracteres) → llamada a la herramienta MCP, reconoce 42 líneas de texto válido + 4 líneas de ruido, en unos 0,6 s, con el mismo resultado que al pasar la ruta directamente.

El servidor automáticamente:

• valida la existencia de la ruta

• decodifica data URI / base64 y escribe en un archivo temporal

• valida el formato admitido (basado en CGImageSource, compatible con JPEG/PNG/HEIC/TIFF/GIF/BMP/WebP)

Formato de salida

• Todas las herramientas devuelven una cadena (JSON) para que el modelo la analice directamente.

• Éxito: {"status": "ok", ...}

• Error: {"status": "error", "error": "..."}

• Las coordenadas del cuadro delimitador (bbox) son valores normalizados (origen en la esquina inferior izquierda, 0~1), coherentes con el framework Vision.

Explicación del mecanismo de activación

MCP utiliza un diseño de protocolo en el que «las herramientas son invocadas por el modelo según sea necesario»; el servidor no puede detectar de forma proactiva que el usuario ha subido una imagen. Para lograr la «activación automática», se necesita la cooperación del cliente/modelo:

Rutas de activación

Convención de prompt recomendada (clave)

Para garantizar una activación del 100 %, añade lo siguiente al AGENTS.md en la raíz del proyecto o al prompt del sistema del modelo:

## 图片处理约定

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

Una vez escrita esta convención en AGENTS.md, clientes como opencode / Claude Desktop enviarán esa instrucción al modelo junto con el prompt del sistema, logrando una verdadera «activación automática».

Configuración de integración del cliente

Sustituye la ruta absoluta de las siguientes configuraciones por la ubicación del proyecto en tu equipo y escríbela en el archivo de configuración del cliente correspondiente.

opencode

Escríbelo en opencode.json (a nivel de proyecto) o en ~/.config/opencode/opencode.json (a nivel de usuario):

{
  "$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
    }
  }
}

Reinicia opencode y verás las 4 herramientas de image-recognition en la lista de herramientas.

Claude Desktop

Escríbelo en ~/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 / clientes MCP stdio genéricos

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

WorkBuddy

Edita ~/.workbuddy/mcp.json, añade image-recognition a mcpServers y reinicia para que surta efecto:

WorkBuddy

Consulta ejemplos de configuración de referencia en el directorio configs/:

• configs/opencode.example.json

• configs/claude-desktop.example.json

• configs/generic-stdio.example.json

Rendimiento y recursos

Sugerencias de optimización:

• Ya se incluye la reducción automática a 4096 px en _load_cg_image, suficiente para la gran mayoría de capturas.

• Si se reconocen muchas imágenes por lotes, se pueden combinar varias llamadas a ocr_image en una sola recognize_image en el cliente para reducir el consumo de tokens de contexto.

• Elegir level="fast" en OCR puede acelerar un 30–50 %, a costa de una ligera pérdida de precisión (texto pequeño, escritura a mano).

Permisos y privacidad

• Totalmente local: todo el reconocimiento se realiza dentro del framework Vision de macOS; los datos no salen del equipo en absoluto, sin necesidad de API Key ni red.

• Permiso de grabación de pantalla (solo lo necesita la herramienta screenshot_and_recognize):

  • En la primera llamada, macOS mostrará un aviso o solicitará autorización en «Ajustes del Sistema > Privacidad y seguridad > Grabación de pantalla».

  • Concede el permiso al proceso anfitrión que ejecuta el servidor MCP (por ejemplo, Terminal, Claude Desktop, opencode).

  • Sin autorización, la herramienta devuelve un mensaje de error claro; no falla en silencio.

Solución de problemas

Sugerencias de ampliación

Para añadir más capacidades de Vision, consulta las funciones existentes en vision_engine.py y añade las solicitudes Vision correspondientes, por ejemplo:

• VNDetectFaceRectanglesRequest — detección de rostros

• VNGenerateAttentionBasedSaliencyImageRequest — regiones de saliencia

• VNDetectDocumentSegmentationRequest — segmentación de regiones de documento (aplicaciones de escaneo)

• VNRecognizeAnimalsRequest — reconocimiento de especies animales (iOS 15+, macOS 12+)

Una vez implementado, basta con añadir un @mcp.tool() en mcp_server.py para exponerlo al modelo.

Estructura de archivos

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 虚拟环境（运行后生成）

Licencia

El código de este proyecto está bajo licencia MIT. Las llamadas al framework Vision están sujetas a la licencia del SDK de Apple y solo pueden ejecutarse en macOS.