eyes-mcp

让任何纯文本 LLM 拥有眼睛。为你的编程代理提供本地视觉。

一条命令 · 零 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. 询问你想使用哪个模型，并根据你的内存和 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 内存。

手动注册

跳过了自动安装，或者遇到安装程序不认识的代理？手动添加即可。

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 的结构相同。

重启代理，然后问：“这张截图里有什么？”

工具

模型预设

隐藏附加项（同样只需一条命令）：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 会显示你的内存/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。模型权重保留各自的许可证（见预设表）；它们在安装时下载，绝不在此重新分发。