Read what's on screen without taking a screenshot.
ScreenRead使AI代理能够访问macOS的可访问性树——与VoiceOver和其他屏幕阅读器相同的结构化数据。您的代理不会捕获像素并将其通过视觉模型馈送，而是会获得描述屏幕上每个UI元素的即时结构化文本。
~100ms 而不是1-3秒。 零幻觉 --它读取操作系统知道的内容，而不是模型认为它看到的内容。
为什么
大多数AI代理工具使用屏幕截图来“查看”屏幕：
- 捕获PNG（~200ms）
- Base64编码和传输（~500KB-2MB）
- 视觉模型处理像素（昂贵、缓慢）
- 模型描述了什么 *认为* 它看到（有时是错误的）
但是，大约90%的代理任务都是基于文本的：“错误说了什么？”，“这个按钮可见吗？”“页面标题是什么？”。截图太夸张了。
ScreenRead跳过所有这些。它直接询问macOS：“此窗口中存在哪些UI元素？”并立即返回结构化文本。
| 截图 | 屏幕阅读 | |
|---|---|---|
| 速度 | 1-3秒 | ~100ms |
| 代币成本 | 高（视觉模型） | 低（文本） |
| 准确度 | 可以产生幻觉文本 | 精确（从操作系统读取） |
| 范围 | 仅限网络（剧作家）或全屏 | 任何macOS应用程序 |
| 不错 | 视觉检查（布局、颜色） | 内容验证、UI状态 |
对于90%与内容和结构有关的任务，请使用ScreenRead。保留需要像素的10%的屏幕截图。
安装
从源代码构建
git clone https://github.com/Bambushu/screenread.git
cd screenread
swift build -c release
cp .build/release/screenread ~/.local/bin/
cp .build/release/screenread-mcp ~/.local/bin/需求
- macOS 13+（Ventura或更高版本）
- 辅助功能权限（系统设置>隐私和安全>辅助功能）
用法
命令行界面
# Read the frontmost app
screenread
# Read a specific app
screenread --app Safari
# Fuzzy match a window title
screenread --window "inbox"
# Text only (no structure)
screenread --app Warp --text-only
# Shallow read (depth 2)
screenread --app Finder --shallow
# Full text, no truncation
screenread --app Terminal --full
# JSON output
screenread --app Safari --json
# Search for text across all open windows
screenread --find "error"
screenread --find "Submit"
# List all open windows
screenread --list
# Filter by role
screenread --app Safari --role AXButton,AXLink
# Exclude roles
screenread --app Safari --ignore AXGroup,AXScrollArea
# List interactive elements with click coordinates
screenread --clickable --app Safari
screenread --clickable --app Finder --json
# Watch for UI changes (poll every 2s, Ctrl+C to stop)
screenread --watch --app Safari
screenread --watch --app Safari --interval 5
# Stream JSONL (one JSON object per node per line)
screenread --stream --app Safari
screenread --stream --app Safari | jq 'select(.role == "AXButton")'MCP服务器
添加到MCP配置中：
克劳德代码 （项目范围 .mcp.json 在项目根目录中）：
{
"mcpServers": {
"screenread": {
"command": "screenread-mcp"
}
}
}克劳德桌面 (~/Library/Application Support/Claude/claude_desktop_config.json):
{
"mcpServers": {
"screenread": {
"command": "/path/to/screenread-mcp"
}
}
}这为任何MCP兼容客户端提供了五个工具：
screenread_snapshot
阅读特定应用程序或窗口的可访问性树。在没有参数的情况下，读取最前面（活动）的应用程序。
| 参数 | 类型 | 说明 |
|---|---|---|
app | string | 应用程序名称（例如。 "Safari") |
window | string | 窗口标题模糊匹配 |
pid | integer | 按进程ID设置的目标 |
depth | integer | 最大树深度（默认值：5）。使用0表示无限制--在大型应用程序上可能很慢。 |
textOnly | boolean | 仅文本，无结构 |
roles | string | 要包含的逗号分隔的AX角色（例如。 "AXButton,AXLink") |
ignore | string | 要排除的逗号分隔的AX角色（例如。 "AXGroup,AXScrollArea") |
screenread_list
列出所有打开的窗口。每个窗口返回一行，格式如下： AppName [PID] — Window Title。无参数。
screenread_find_text
在所有打开的窗口中搜索可见文本。纯子字符串匹配（无正则表达式）。
| 参数 | 类型 | 说明 |
|---|---|---|
query | string | 要搜索的纯文本子字符串（必填） |
caseSensitive | boolean | 区分大小写（默认值：false） |
结果以100场比赛为限。使用 screenread_snapshot 通过特定的应用程序获得更有针对性的结果。
screenread_clickable
列出交互式元素（按钮、链接、文本字段）及其点击坐标。
| 参数 | 类型 | 说明 |
|---|---|---|
app | string | 应用程序名称（例如。 "Safari") |
window | string | 窗口标题模糊匹配 |
pid | integer | 按进程ID设置的目标 |
roles | string | 覆盖默认交互角色（例如。 "AXButton,AXLink") |
返回一个包含角色、标签、中心x/y坐标和状态（启用/禁用/聚焦/选中）的表。
screenread_watch
观察应用程序在一段时间内的UI变化。
| 参数 | 类型 | 说明 |
|---|---|---|
app | string | 应用程序名称（例如。 "Safari") |
window | string | 窗口标题模糊匹配 |
pid | integer | 按进程ID设置的目标 |
duration | integer | 观看时长（秒）（默认值：10，最大值：60） |
interval | integer | 轮询间隔（秒）（默认值：2，分钟：1） |
textOnly | boolean | 仅比较文本内容（默认值：false） |
以给定的间隔轮询可访问性树，并报告添加、删除和值/状态更改。
建筑
screenread/
├── Sources/
│ ├── ScreenReadCore/ # Shared library
│ │ ├── AXHelpers.swift # Shared AX attribute accessors
│ │ ├── AXTreeWalker.swift # Recursive accessibility tree traversal + streaming callback
│ │ ├── Formatter.swift # Text tree, text-only, JSON, clickable output
│ │ ├── MCPProtocol.swift # JSON-RPC types, tool dispatch, parameter validation
│ │ ├── StreamFormatter.swift # JSONL single-node encoder
│ │ ├── TargetResolver.swift # App/window/PID resolution with fuzzy matching
│ │ ├── TreeDiffer.swift # Compare two tree snapshots for changes
│ │ └── Types.swift # AXNode, WalkResult, WindowInfo, errors
│ ├── screenread/ # CLI (uses ArgumentParser)
│ └── screenread-mcp/ # MCP server (Content-Length framed stdio)
└── Tests/
└── ScreenReadCoreTests/ # 27 tests across 4 suites核心图书馆(ScreenReadCore)CLI和MCP服务器都是围绕它的精简包装器。
平台
仅限macOS。ScreenRead使用苹果的 AXUIElement 可访问性API，它在其他平台上没有对等功能。Linux需要AT-SPI，Windows需要UI自动化——这是根本不同的API。
许可证
麻省理工学院