image-recognition-mcp

Ein MCP-Server für Bilderkennung auf Basis des lokalen macOS-Vision-Frameworks – damit auch KI-Modelle ohne visuelle Fähigkeiten Screenshots und Bilder „sehen" können.

Stellt KI-Clients (opencode / Claude Desktop / Cursor / Cline usw.) 4 MCP-Tools bereit:
OCR-Texterkennung / Bildhauptobjekt-Klassifikation / Umfassende Erkennung / Screenshot und Erkennung. Vollständig lokale Inferenz, Daten verlassen das Gerät nicht.

Inhaltsverzeichnis

• Eigenschaften

• Architektur

• Schnellstart

• MCP-Tool-Beschreibung

• Eingabe- und Ausgabeformat

• Erläuterung des Auslösemechanismus

• Client-Integrationskonfiguration

• Leistung und Ressourcen

• Berechtigungen und Datenschutz

• Fehlerbehebung

• Erweiterungsvorschläge

Related MCP server: npu-vision-fallback

Eigenschaften

• 100 % lokale Inferenz: Basiert auf dem Apple-Vision-Framework (VNRecognizeTextRequest + VNClassifyImageRequest), keine Netzwerkanfragen, keine externen API-Aufrufe.

• Gemischte chinesisch-englische OCR: Unterstützt Chinesisch (zh-Hans), Englisch und 20+ Sprachen, einschließlich Handschrifterkennung, mit wählbarer Genauigkeitsstufe (accurate / fast).

• Bildhauptobjekt-/Szenenklassifikation: Gibt Kategorielabels mit Konfidenz zurück, das Modell kann daraus natürliche Sprachbeschreibungen generieren.

• Drei Bildquellen: Lokaler Pfad, data:image/png;base64,...-URI, reines Base64 (PNG-Magie-Byte-Prüfung).

• Automatische Verkleinerung großer Bilder: Bilder größer als 4096px werden standardmäßig automatisch als Thumbnail verkleinert, bevor sie erkannt werden – schneller und speicherschonender.

• Strukturierte JSON-Ausgabe: Alle Tools geben ein einheitliches {status, ...}-JSON zurück, einschließlich Konfidenz und normalisiertem Begrenzungsrahmen, sodass das Modell es leicht parsen und referenzieren kann.

• Optionale Screenshots: Direkter Aufruf des screencapture-Befehls zum Aufnehmen und Erkennen von Screenshots (erfordert Bildschirmaufnahme-Berechtigung).

Architektur

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

Schnellstart

Systemanforderungen

• macOS 13+ (14+ empfohlen, beste chinesische OCR-Ergebnisse mit dem Vision-Framework)

• Python 3.10+ (getestet mit 3.13.12)

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

Installation

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

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

Selbsttest

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

Erwartete Ausgabe: 3 Textzeilen (MacBook Air 图片识别测试 / Hello Vision OCR 12345 / 日期：2026-08-04 13:30) werden vollständig erkannt, und das Bildklassifikationsergebnis ist plausibel (document/printed_page/screenshot usw.).

Direkter CLI-Aufruf der Engine (optional)

# 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-Tool-Beschreibung

Nach dem Start stellt der Server dem Client 4 Tools bereit:

1. ocr_image – Text aus Bildern extrahieren (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，过滤图标/符号误识噪声
}

Hinweis zu filter_noise: Filtert automatisch Fehlerkennungs-Rauschen von Symbolen in Screenshots (z. B. •••, ③, ein einzelnes 8/凸), behält aber Zahlenfolgen mit möglicher geschäftlicher Bedeutung (Beträge, Kartennummern, Transaktions-IDs, Zeiten usw.). Gefilterte Zeilen werden separat im zurückgegebenen Feld noise abgelegt, sodass keine Informationen verloren gehen; für das vollständige Roh-Ergebnis setze filter_noise: false.

Rückgabe:

{
  "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 – Umfassende Erkennung

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

Rückgabe:

{
  "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 – Hauptobjekt-/Szenenklassifikation

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

Rückgabe:

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

label ist auf Englisch (z. B. Animal / Landscape / Food / Vehicle) und wird vom aufrufenden Modell selbst interpretiert und übersetzt.

4. screenshot_and_recognize – Screenshot aufnehmen und erkennen

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

Nimmt den gesamten Bildschirm auf → OCR. Erfordert die Bildschirmaufnahme-Berechtigung, siehe Berechtigungen und Datenschutz.

Eingabe- und Ausgabeformat

Eingabeformat (image-Parameter)

Praxistest: Desktop-Screenshot 256KB → Base64-data-URI (ca. 340.000 Zeichen) → MCP-Tool-Aufruf, erkennt 42 Zeilen gültigen Text + 4 Zeilen Rauschen, Dauer ca. 0,6 s, Ergebnis identisch mit direkter Pfadübergabe.

Der Server automatisiert:

• Pfad-Existenzprüfung

• data-URI-/Base64-Dekodierung und Schreiben in eine temporäre Datei

• Formatunterstützungsprüfung (basiert auf CGImageSource, kompatibel mit JPEG/PNG/HEIC/TIFF/GIF/BMP/WebP)

Ausgabeformat

• Alle Tools geben einen String (JSON) zurück, damit das Modell ihn direkt parsen kann.

• Erfolg: {"status": "ok", ...}

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

• Begrenzungsrahmen-Koordinaten (bbox) sind normalisierte Werte (Ursprung unten links, 0~1), konsistent mit dem Vision-Framework.

Erläuterung des Auslösemechanismus

MCP verwendet das Protokolldesign „Tool wird vom Modell bei Bedarf aufgerufen" – der Server kann nicht aktiv wahrnehmen, dass der Benutzer ein Bild hochgeladen hat. Für eine „automatische Auslösung" ist die Zusammenarbeit von Client/Modell erforderlich:

Auslösepfade

Empfohlene Prompt-Konvention (entscheidend)

Für 100 % Auslösung in die AGENTS.md im Projektstammverzeichnis oder in die System-Prompts des Modells aufnehmen:

## 图片处理约定

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

Nachdem diese Konvention in AGENTS.md geschrieben wurde, senden Clients wie opencode / Claude Desktop die Anweisung zusammen mit dem System-Prompt an das Modell – das ermöglicht echte „automatische Auslösung".

Client-Integrationskonfiguration

Ersetze die absoluten Pfade in den folgenden Konfigurationen durch den Projektpfad auf deinem Rechner und schreibe sie dann in die Konfigurationsdatei des jeweiligen Clients.

opencode

In opencode.json (Projektebene) oder ~/.config/opencode/opencode.json (Benutzerebene) schreiben:

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

Nach dem Neustart von opencode erscheinen die 4 Tools von image-recognition in der Tool-Liste.

Claude Desktop

In ~/Library/Application Support/Claude/claude_desktop_config.json schreiben:

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

Cursor / Cline / allgemeine stdio-MCP-Clients

{
  "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 bearbeiten und image-recognition zu mcpServers hinzufügen; nach dem Neustart aktiv:

WorkBuddy

Referenz-Konfigurationsbeispiele findest du im Verzeichnis configs/:

• configs/opencode.example.json

• configs/claude-desktop.example.json

• configs/generic-stdio.example.json

Leistung und Ressourcen

Optimierungsvorschläge:

• _load_cg_image enthält bereits die automatische 4096px-Verkleinerung, die für die meisten Screenshots ausreichend ist.

• Bei der Erkennung vieler Bilder in Stapeln können mehrere ocr_image-Aufrufe im Client zu einem einzigen recognize_image zusammengefasst werden, um Kontext-Token zu sparen.

• Mit level="fast" bei der OCR ist eine Beschleunigung um 30–50 % möglich, auf Kosten einer leicht geringeren Genauigkeit (kleine Schrift, Handschrift).

Berechtigungen und Datenschutz

• Vollständig lokal: Alle Erkennungen erfolgen im macOS-Vision-Framework, Daten verlassen das Gerät überhaupt nicht, keine API-Keys oder Netzwerk erforderlich.

• Bildschirmaufnahme-Berechtigung (nur für das Tool screenshot_and_recognize erforderlich):

  • Beim ersten Aufruf fordert macOS die Autorisierung an oder verlangt sie unter „Systemeinstellungen > Datenschutz & Sicherheit > Bildschirmaufnahme".

  • Erteile die Berechtigung dem Host-Prozess, der den MCP-Server ausführt (z. B. Terminal, Claude Desktop, opencode).

  • Ohne Autorisierung gibt das Tool eine klare Fehlermeldung zurück und schlägt nicht still fehl.

Fehlerbehebung

Erweiterungsvorschläge

Um weitere Vision-Fähigkeiten hinzuzufügen, können die vorhandenen Funktionen in vision_engine.py als Referenz für entsprechende Vision-Requests dienen, z. B.:

• VNDetectFaceRectanglesRequest – Gesichtserkennung

• VNGenerateAttentionBasedSaliencyImageRequest – Salienzregionen

• VNDetectDocumentSegmentationRequest – Dokumentbereichssegmentierung (Scan-Anwendungen)

• VNRecognizeAnimalsRequest – Tierartenerkennung (iOS 15+, macOS 12+)

Nach der Implementierung genügt ein neuer @mcp.tool() in mcp_server.py, um das Tool dem Modell zur Verfügung zu stellen.

Dateistruktur

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

Lizenz

Der Code dieses Projekts steht unter der MIT-Lizenz. Die Nutzung des Vision-Frameworks unterliegt der Apple-SDK-Lizenz und ist nur unter macOS ausführbar.