de en es ja ko ru zh

image-recognition-mcp

Name: image-recognition-mcp
Author: carlleilzj

by carlleilzj

Overview Schema Source Related Servers Discussions Admin

Python

Local

image-recognition-mcp

macOS ローカル Vision フレームワークに基づく画像認識 MCP サーバー —— 視覚を持たない AI モデルでもスクリーンショットや画像を「見る」ことができるようにします。

AI クライアント（opencode / Claude Desktop / Cursor / Cline など）に 4 つの MCP ツールを提供：
OCR 文字認識 / 画像主体分類 / 総合認識 / スクリーンショット取得＆認識。すべてローカル推論で、データは端末外に出ません。

特徴

100% ローカル推論：Apple Vision フレームワーク（VNRecognizeTextRequest + VNClassifyImageRequest）に基づき、ネットワークリクエストゼロ、外部 API 呼び出しゼロ。
中日英混在 OCR：中国語（zh-Hans）、英語および 20 以上の言語に対応、手書き文字認識を含み、精度モード（accurate / fast）を選択可能。
画像主体/シーン分類：カテゴリラベルと信頼度を返し、モデルはこれに基づいて自然言語の説明を生成できます。
3 種類の画像ソース：ローカルパス、data:image/png;base64,... URI、純粋な base64（PNG マジックナンバー検証）。
超大画像の自動縮小：デフォルトで 4096px を超える画像は自動的にサムネイルを生成してから認識するため、高速化・メモリ節約。
構造化 JSON 出力：すべてのツールが統一された {status, ...} JSON を返し、信頼度と正規化されたバウンディングボックスを含むため、モデルが解析・参照しやすい。
オプションのスクリーンショット：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` パラメータ）

形式	例	説明
ローカル絶対パス	`/Users/me/Pictures/x.png`	最も一般的
相対パス	`shot.png` / `./imgs/x.png`	クライアントの作業ディレクトリ基準
data URI	`data:image/png;base64,iVBORw0KG...`	ユーザーが画像を直接貼り付ける際に一般的
純粋な base64	`iVBORw0KG...`	フォールバック（PNG マジックナンバー自動検証）

実測：デスクトップスクリーンショット 256KB → base64 data URI（約 34 万文字）→ MCP ツール呼び出し、有効なテキスト 42 行 + ノイズ 4 行を認識、所要時間約 0.6 秒、パス直接渡しと結果は同一。

サーバーは自動的に：

パスの存在検証
data URI / base64 デコード後、一時ファイルに書き込み
形式サポート検証（CGImageSource ベース、JPEG/PNG/HEIC/TIFF/GIF/BMP/WebP 対応）

出力形式

すべてのツールが文字列（JSON）を返し、モデルが直接解析可能。
成功：{"status": "ok", ...}
失敗：{"status": "error", "error": "..."}
バウンディングボックス座標（bbox）は正規化値（原点は左下、0〜1）で、Vision フレームワークと一致。

トリガー機構の説明

MCP は「ツールはモデルがオンデマンドで呼び出す」というプロトコル設計のため、サーバーはユーザーが画像をアップロードしたことを能動的に感知できません。「自動トリガー」を実現するには、クライアント/モデル側の連携が必要です：

トリガーパス

ユーザー操作	クライアントコンテキスト	モデルの挙動	ツール呼び出し
opencode で `@参照` で画像を添付	画像の絶対パスがコンテキストに注入	視覚なしモデルがパスを認識 → `ocr_image(path)` を呼び出し	✅ 自動
画像をセッションにドラッグ＆ドロップ / スクリーンショットを貼り付け	一部のクライアントは data URI として注入	視覚なしモデルが data URI を認識 → `ocr_image(uri)` を呼び出し	✅ 自動
ユーザーが「これは私のスクリーンショットです」と口頭で述べて貼り付け	パス / data URI がコンテキストに入る	同上	✅ 自動

推奨プロンプト規約（重要）

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 を再起動すると、ツールリストに image-recognition の 4 つのツールが表示されます。

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

パフォーマンスとリソース

画像サイズ	OCR 所要時間（M4 Air 実測）	メモリピーク
1200×420（テスト画像）	~100 ms	< 50 MB
1920×1080（スクリーンショット）	150–300 ms	~80 MB
4096×4096（4K）	400–800 ms	~150 MB
8000×8000（超大画像）	自動で 4096px に縮小、約 500–1200 ms	~200 MB

最適化の提案：

_load_cg_image に 4096px の自動縮小が組み込まれており、ほとんどのスクリーンショットで十分です。
大量の画像を一括認識する場合は、クライアント側で複数の ocr_image 呼び出しを 1 回の recognize_image にまとめると、コンテキストのトークン消費を削減できます。
OCR で level="fast" を選択すると 30〜50% 高速化できますが、精度が若干低下します（小さい文字、手書き文字）。

権限とプライバシー

完全ローカル：すべての認識は macOS Vision フレームワーク内で完了し、データは完全に端末外に出ません。API キーやネットワークは一切不要です。
画面収録権限（screenshot_and_recognize ツールのみ必要）：
- 初回呼び出し時に、macOS がポップアップを表示するか、「システム設定 > プライバシーとセキュリティ > 画面収録」で承認を求めます。
- この MCP サーバーを実行するホストプロセス（ターミナル、Claude Desktop、opencode など）に権限を付与してください。
- 未承認の場合、ツールは明確なエラーメッセージを返し、サイレントに失敗することはありません。

トラブルシューティング

問題	原因と解決
`ModuleNotFoundError: No module named 'pyobjc.framework.Vision'`	依存関係が未インストール。venv 内で `pip install -r requirements.txt` を実行。
`ModuleNotFoundError: No module named 'mcp.server.fastmcp'`	`fastmcp` は mcp<2.0 でのみ使用。本プロジェクトは 1.x と 2.0 に対応。ダウングレードする場合：`pip install 'mcp>=1.2,<2.0'`。
OCR 中国語認識が空/文字化け	画像が鮮明か確認。中国語画像の縮小が小さすぎる（< 16px フォントサイズ）と認識に失敗します。`level="accurate"` を試し、フォントサイズを大きくしてください。
分類結果が異常（純テキスト画像で "sport" が返るなど）	Vision の分類は一部のシーンで境界があいまいなのは正常な動作。`min_confidence` を高く（0.2〜0.5）設定してノイズをフィルタリング。
`screenshot_and_recognize` で「スクリーンショット失敗」エラー	画面収録が未承認。「システム設定 > プライバシーとセキュリティ > 画面収録」でホストアプリに権限を付与して再試行。
MCP クライアント接続後、ツールリストが空	`command` のパスが正しいか確認。venv 内の python インタプリタで `import vision_engine` が成功することを確認。

拡張提案

さらに Vision 機能を追加する場合は、vision_engine.py の既存関数を参考に対応する Vision リクエストを追加できます。例：

VNDetectFaceRectanglesRequest — 顔検出
VNGenerateAttentionBasedSaliencyImageRequest — 顕著性領域
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 フレームワークの呼び出しは Apple SDK のライセンス制約を受け、macOS 上でのみ実行可能です。

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityMaintained

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

UI Verify A
io.github.igrlk
MCP server for visual regression testing: triage a PR's UI diffs from your coding agent.
Testing & QA Tools CI/CD & DevOps
14118
Frenchie A
io.github.Lab94
OCR, transcription, file extraction, and image generation for AI agents via MCP.
AI & Machine Learning Image & Video Processing Speech Processing
72
mcp-qwen-imageOAuth
io.github.AceDataCloud
MCP server for Qwen Image 3 AI image generation
AI & Machine Learning Image & Video Processing
1
KodyOAuth
io.github.kentcdodds
Personal assistant MCP server with search, execute, packages, jobs, secrets, and integrations.
Developer Tools Code Execution Command Line
2659

Related MCP Servers

Vison-MCP
Image & Video Processing AI & Machine Learning
Lin-zhibo
A
license
A
quality
D
maintenance
MCP server for vision AI — screenshots to code, OCR, error diagnosis, and image analysis via OpenAI-compatible APIs.
Updated 3 months ago (2026-06-10 18:47 UTC)
8
2
MIT
npu-vision-fallback
Image & Video Processing OS Automation
Byte-Naut
A
license
A
quality
F
maintenance
Provides an MCP server for local low-power screen vision, enabling AI agents to perform OCR and UI detection on inaccessible screens (games, remote desktops) using NPU acceleration and system OCR.
Updated 2 months ago (2026-07-31 16:19 UTC)
5
1
MIT
lucid-apple-mcp
Lucid-Systems-LLC
A
license
Not graded
quality
C
maintenance
MCP server that gives Claude and local LLMs access to Apple's on-device frameworks — Vision OCR, NSDataDetector, and Apple Intelligence FoundationModels. Everything runs on your Mac with zero data leaving.
Updated 3 months ago (2026-06-19 17:12 UTC)
1
MIT
mcp-vision
Image & Video Processing AI & Machine Learning
MikeyBeez
F
license
A
quality
D
maintenance
MCP server for vision capabilities, enabling screenshot, camera, and image analysis using Ollama vision models.
Updated 8 months ago (2026-01-14 19:30 UTC)
4
1
-

image-recognition-mcp

目次

特徴

アーキテクチャ

クイックスタート

環境要件

インストール

セルフテスト

コマンドラインからエンジンを直接呼び出す（オプション）

MCP ツール説明

1. ocr_image — 画像から文字を抽出（OCR）

2. recognize_image — 総合認識

3. describe_image — 主体/シーン分類

4. screenshot_and_recognize — スクリーンショット取得＆認識

入出力形式

入力形式（image パラメータ）

出力形式

トリガー機構の説明

トリガーパス

推奨プロンプト規約（重要）

クライアント接続設定

opencode

Claude Desktop

Cursor / Cline / 汎用 stdio MCP クライアント

WorkBuddy

WorkBuddy

パフォーマンスとリソース

権限とプライバシー

トラブルシューティング

拡張提案

ファイル構造

ライセンス

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

Vison-MCP

npu-vision-fallback

lucid-apple-mcp

mcp-vision

1. `ocr_image` — 画像から文字を抽出（OCR）

2. `recognize_image` — 総合認識

3. `describe_image` — 主体/シーン分類

4. `screenshot_and_recognize` — スクリーンショット取得＆認識

入力形式（`image` パラメータ）