ScreenLens MCP

让 AI Agent 看见你的屏幕、在屏幕上直接指给你看的 MCP 服务。

配好就能用，不需要打开任何窗口——它在后台以无 GUI 服务运行，Agent 调用时才拉起。

• 🖥 screen_capture — 截取屏幕，返回带坐标网格的图片

• 📷 camera_capture — 拍一张摄像头画面（每次都会弹窗请你确认）

• ✏️ annotate — 在真实屏幕上画框 / 圈 / 箭头 / 文字气泡，默认 5 秒后自动消失

• 👁 watch_next — 阻塞观察，画面出现变化才返回截图，本地检测不花 token

• 🗂 list_displays / list_cameras / list_windows — 枚举屏幕、摄像头、窗口

Windows 10/11。macOS / Linux 未实现。

实际效果

以下都截自真实使用录像，标注画在用户自己的屏幕上。

左侧是摄像头画面（正对着桌上的面包板），右侧是 Agent 的解释。①②③ 三个标号把「先接这里」「先确认极性」「把镜头放大」直接指在实物上。

Related MCP server: vision-input

快速开始

需要 Node.js 18+。

git clone <this-repo> screenlens-mcp
cd screenlens-mcp
npm install
npm run build

然后接入你用的客户端（可多选）：

node scripts/install-mcp.mjs dsh     # DeepSeek Harness
node scripts/install-mcp.mjs codex   # Codex
node scripts/install-mcp.mjs claude  # Claude Code

脚本会写入对应客户端的 MCP 配置，并把原有配置备份成 *.bak-screenlens-<时间戳>。

重启客户端后，直接对 Agent 说「看一下我的屏幕，告诉我哪里报错了」即可。

手动配置

想自己写配置的话（以 Claude Code / Codex 的 stdio 格式为例）：

{
  "mcpServers": {
    "screenlens": {
      "command": "node",
      "args": ["/绝对路径/screenlens-mcp/mcp/screenlens-mcp.mjs"]
    }
  }
}

首次调用工具时，它会自动在后台启动 ScreenLens 服务（无窗口、无托盘弹窗）， 之后所有调用都走这个常驻服务。你也可以手动启动：

node scripts/start.mjs --service

工具说明

坐标一律是归一化 0~1000：图片左上角 (0,0)，右下角 (1000,1000)，与分辨率无关。 返回的图片默认叠加半透明橙色网格（每 100 一条），用来精确读坐标，网格不属于画面内容。

标注类型

[
  {"type": "box",    "bbox": [x1, y1, x2, y2], "label": "说明"},
  {"type": "circle", "bbox": [x1, y1, x2, y2], "label": "说明"},
  {"type": "arrow",  "from": [x, y], "to": [x, y], "label": "说明"},
  {"type": "text",   "at": [x, y], "text": "可以多行\n也可以带尾巴", "to": [x, y]}
]

text 是独立文字气泡：at 是气泡中心，自动折行、超出屏幕自动内收，to 可选， 画一条引线指向目标。适合直接在画面上写解释和改法。

隐私

这几条是代码层强制的，改参数绕不过去：

• 摄像头必须确认：每次 camera_capture 都会弹出系统对话框，可选「拒绝 / 仅这一次 / 10 分钟内允许」， 60 秒不选视为拒绝。拒绝后 30 秒内的重复请求直接被拒，防止 Agent 反复弹窗。 授权只存在内存里，服务重启即失效，托盘菜单可随时撤销。

• 标注不会挡住观察：watch_next 会忽略屏幕上标注所覆盖的区域，所以标注挂着也能继续观察， 且标注的出现/消失本身不会触发提醒。

• 数据不出本机：截图、摄像头画面只回传给调用你的那个 Agent，ScreenLens 自己不做任何上传。

• 隐私黑名单：可在设置里配置程序名单，这些程序在前台时自动观察一律暂停。

工作原理

┌────────────┐   stdio (MCP)    ┌──────────────────┐   127.0.0.1 + token   ┌───────────────────┐
│  AI Agent  │ ◄──────────────► │ screenlens-mcp   │ ◄───────────────────► │ ScreenLens 服务   │
│ (DSH/Codex)│                  │  .mjs（零依赖）  │                       │ (Electron 无窗口) │
└────────────┘                  └──────────────────┘                       └───────────────────┘

• mcp/screenlens-mcp.mjs 是零依赖的 stdio MCP 服务，只做协议转换。

• 干活的 ScreenLens 服务是个 Electron 进程，但以 --service 模式运行：窗口永不显示， 只保留托盘图标（打开设置 / 撤销摄像头授权 / 退出）。

• 两者通过 %APPDATA%\ScreenLens\bridge.json 里的端口和一次性 token 通信，只监听 127.0.0.1。

• 服务没起来时，MCP 会自动拉起它，用户无需手动启动。

为什么需要 Electron

截屏、屏幕覆盖层、摄像头取帧都要 Chromium 的能力（desktopCapturer、透明置顶窗口、getUserMedia）。 Electron 二进制随 npm install 自动下载，不需要你额外安装或打开任何应用。

目录结构

mcp/screenlens-mcp.mjs     stdio MCP 服务（协议层，零依赖）
src/main/                  主进程：服务模式、截屏、覆盖层、摄像头确认、观察循环、本地 bridge
src/shared/                标注解析、几何布局、SVG 绘制、画面 diff（纯逻辑，可单测）
src/renderer/              渲染进程：加网格/缩放、摄像头取帧（服务模式下窗口不显示）
src/overlay/               屏幕覆盖层页面
scripts/                   build / setup / start / e2e / 可视化测试

src/renderer 里的聊天界面是可选的调试与设置入口，MCP 用法完全不需要它。

开发

npm run build      # 构建
npm run typecheck  # 类型检查
npm start          # 带 GUI 启动（调试用）
npm run visual     # 无头可视化测试，输出 .e2e/*.png
npm run e2e        # MCP 端到端测试
node scripts/run-ts.mjs scripts/test-diff.ts   # 观察算法单测

License

MIT