eyes-mcp

テキストのみのLLMに目を与えます。コーディングエージェントのためのローカルビジョン。

1コマンド・APIキー不要・あなたのマシンから何も出て行かない

DeepSeek、GLM、Qwen-Coder、Llama… 優れたモデルだが、すべて目が見えない。

❌ 目がない場合

テキストのみのモデルを実行しているエージェント（Claude Code / Codex / Cursor 経由）にスクリーンショットを貼り付けます:

> Here's the error in my UI, fix it  [screenshot.png]

I'm sorry — I cannot see images. Please describe the error in text.

✅ 目がある場合

代わりに、エージェントはローカルのVLM + OCRを呼び出し、スクリーンショットを自分で読み取ります:

> Here's the error in my UI, fix it  [screenshot.png]

I see a React hydration error in `CartDrawer.tsx:142`. The OCR shows:
"Hydration failed because the server rendered HTML didn't match the client." …

クイックスタート

git clone https://github.com/JamesbbBriz/eyes-mcp
cd eyes-mcp && ./scripts/install.sh

これだけです。インストーラは:

1. 希望するモデルを尋ねます。RAMとGPUから計算された推奨モデル付きです（EYES_PRESET または --yes で質問をスキップできます）。

2. 依存関係をインストールし、モデルをダウンロードします（約0.3〜3.5GB、再開可能）。

3. Claude Code / Codex / Cursor の設定を読み取り、各モデルをモダリティデータベースと照合して、テキストのみのモデルを実行しているエージェントを検出します。

4. 必要な場所にのみ eyes-mcp を登録します。マルチモーダルエージェントは自動的にスキップされます。

# options:
EYES_PRESET=fast ./scripts/install.sh            # Qwen3.5-0.8B, natively multimodal
HF_ENDPOINT=https://hf-mirror.com ./install.sh  # mainland-CN mirror
./install.sh --yes                              # accept all recommendations, no prompts
./install.sh --dry-run                          # preview without changing anything

モダリティチェックだけが必要ですか？ python3 scripts/detect_modality.py

必要条件: Python ≥3.11、llama.cpp（brew install llama.cpp）、約1GBのRAM。

手動登録

自動インストールをスキップした場合、またはインストーラが認識しないエージェントは？手動で追加してください。

Claude Code（~/.claude.json → mcpServers）:

"eyes-mcp": {
  "command": "uv",
  "args": ["--directory", "/ABS/PATH/eyes-mcp", "run", "eyes-mcp"],
  "env": { "EYES_PRESET": "lfm-450m" }
}

Codex（~/.codex/config.toml）:

[mcp_servers.eyes-mcp]
command = "uv"
args = ["--directory", "/ABS/PATH/eyes-mcp", "run", "eyes-mcp"]
env = { EYES_PRESET = "lfm-450m" }

Cursor（.cursor/mcp.json）: Claude Code と同じ形式です。

エージェントを再起動して、次のように尋ねてください: 「このスクリーンショットには何が写っていますか？」

ツール

モデルプリセット

隠しエクストラ（同じく1コマンド）: smol500（SmolVLM2-500M）、paddle（PaddleOCR-VL-1.6）、qwen3-2b（Qwen3-VL-2B）。

他のGGUFでも動作します。環境変数で指定して、プリセットを完全にスキップできます:

EYES_MODEL_DIR=~/models/my-vlm  VLM_MODEL_FILE=model-Q4.gguf  VLM_MMPROJ_FILE=mmproj.gguf

プリセットとして同梱されていない良い候補: LFM2.5-VL-1.6B/3B、InternVL3.5-2B/4B、MiniCPM-V-4.6、DeepSeek-OCR、dots.ocr、gemma-3n-E2B、moondream2。llama.cpp が mmproj ファイル付きでサポートしているものなら何でも動作します。

いつでも切り替え可能: EYES_PRESET を設定して ./scripts/download_models.sh を再度実行してください。どれがいいか分からない？ python3 scripts/choose_model.py が RAM/GPU を表示し、推奨をマークします。

仕組み

Claude Code / Codex / Cursor
      │ MCP stdio
      ▼
eyes-mcp  (stateless, mcp SDK 2.x)
   ├─ analyze_image → llama.cpp llama-server (local VLM)  "understand"
   └─ ocr_image     → RapidOCR (onnx, ~20MB)             "extract text"

• ライフサイクルはエージェントに追従: VLMサーバーはMCPの開始時に起動し、エージェントの終了時にシャットダウンするため、孤立プロセスや常駐デーモンの管理が不要です。

• フローティングポート: VLMは固定ポートにバインドしないため（「8080は既に使用中」とはおさらば）、他のローカルサービスと共存できます。

• 外部VLMの再利用: すでに VLM_BASE_URL でVLMを実行している場合、eyes-mcp は独自に起動する代わりにそれを使用します。

なぜ？

現在、最も安価で優れたコーディングモデル（DeepSeek-V4-Flash、GLM-5.x、Qwen-Coder）はテキストのみです。すべてのハーネスはスクリーンショットを貼り付けられることを前提としていますが、これらのモデルはどれも黙って失敗します。eyes-mcp は欠けているサイドカーです。小型のローカルVLMとOCRを、エージェントがすでに理解しているライフサイクルで包み込みます。

ロードマップ

• 遅延VLM起動（MCP開始時ではなく、最初のツール呼び出し時に起動）

• screenshot_analyze（ファイル不要で画面を取得）

• PDFページ → ビジョン

• npx eyes-mcp ワンライナーインストーラ

• モデルごとのプロンプトテンプレート（llama.cpp OCRモデルには特定のプロンプトが必要）

よくある質問

エージェントのモデルは重要ですか？ これが役立つためには、モデルがテキストのみでなければならないという点だけです。マルチモーダルモデル（GPT、Claude、GLM-V）はすでに画像を見られるため、気にする必要はありません。

GPUは必要ですか？ いいえ。CPUでも問題なく動作し、llama.cpp はApple MetalまたはCUDAがあれば自動的に使用します。

モデルはどこに保存されますか？ ~/.eyes-mcp/models/<preset>/。リセットするには削除してください。

ライセンス

MIT。モデルの重みはそれぞれのライセンスに従います（プリセット表を参照）。インストール時にダウンロードされ、ここで再配布されることはありません。