macOS应用交互服务

AxMCP

MCP服务器，允许Claude（或任何LLM）通过Accessibility API查看macOS应用程序并与之交互。它可以读取UI树，查找元素，单击按钮，键入文本，并观察变化。

快速开始

使用Claude Desktop运行的三个步骤：

第一步：构建它

git clone https://github.com/adamrdrew/axmcp.git
cd axmcp
swift build -c release

第二步：告诉克劳德桌面

在文本编辑器中打开此文件：

~/Library/Application Support/Claude/claude_desktop_config.json

如果文件不存在，请创建它。添加以下内容（将路径替换为您克隆仓库的位置）：

{
  "mcpServers": {
    "accessibility": {
      "command": "/Users/YOURUSERNAME/axmcp/.build/release/axmcp"
    }
  }
}

保存文件并重新启动Claude Desktop。

步骤3：授予辅助功能权限

第一次使用它时，macOS会请求许可。如果没有，请手动执行：

1. 打开 系统设置
2. 首选 隐私和安全 > 无障碍
3. 点击 + 按钮
4. 添加 克劳德桌面 （在/Applications中找到它）
5. 重新启动克劳德桌面

就是这样。打开克劳德桌面，问它这样的问题：

“我现在打开了哪些窗户？”

或

“查看Finder UI并描述您看到的内容。”

Claude将自动使用辅助工具。

它能做什么？

你不需要直接调用这些工具。只要用自然语言描述你想要什么，克劳德就会想出使用哪些工具。

安装

家酿

brew tap adamrdrew/axmcp
brew install axmcp

如果你通过Homebrew安装，你的Claude Desktop配置会更简单：

{
  "mcpServers": {
    "accessibility": {
      "command": "axmcp"
    }
  }
}

从源头构建

需要macOS 13.0+和Swift 6。

git clone https://github.com/adamrdrew/axmcp.git
cd axmcp
swift build -c release

二进制文件将位于 .build/release/axmcp.

安全特性

写入操作（单击、键入）内置了安全防护装置：

只读模式 禁用所有写入操作：

{
  "mcpServers": {
    "accessibility": {
      "command": "axmcp",
      "args": ["--read-only"]
    }
  }
}

应用程序阻止列表 防止写入敏感应用程序。默认情况下，终端、iTerm2、系统设置和钥匙链访问被阻止。读取仍然适用于被阻止的应用程序。

速率限制 防止自动化失控（默认值：10个动作/秒）。

配置

自定义配置示例：

{
  "mcpServers": {
    "accessibility": {
      "command": "axmcp",
      "env": {
        "AXMCP_RATE_LIMIT": "5",
        "AXMCP_BLOCKLIST": "com.example.app1,com.example.app2"
      }
    }
  }
}

MCP工具参考

获取_树

获取应用程序的可访问性树。

参数：

• app （必填）：应用程序名称（例如“Finder”）或数字PID
• depth （可选）：最大树深度（默认值：3）

退货： 具有角色、标题、值、子项、动作和元素路径的层次树。

请求示例：

{ "app": "Finder", "depth": 2 }

find_element

搜索符合条件的UI元素。

参数：

• app （必填）：应用程序名称或PID
• role （可选）：元素角色（例如“按钮”、“文本字段”）
• title （可选）：要匹配的标题子字符串（不区分大小写）
• max_results （可选）：最大结果（默认值：20）

请求示例：

{ "app": "Finder", "role": "Button", "title": "Save" }

get_focused_element

获取当前聚焦的UI元素。

参数：

• app （可选）：应用程序名称或PID。省略全系统重点。

请求示例：

{}

list_windows

列出应用程序或系统范围的窗口。

参数：

• app （可选）：应用程序名称或PID。省略所有窗口。

请求示例：

{ "app": "Finder" }

性能动作

单击按钮，选择菜单项，并执行其他UI操作。

参数：

• app （必填）：应用程序名称或PID
• elementPath （必填）：元素路径从 get_ui_tree 或 find_element
• action （必填）：动作名称(AXPress, AXPick, AXShowMenu, AXConfirm, AXCancel, AXRaise, AXIncrement, AXDecrement)

请求示例：

{
  "app": "Finder",
  "elementPath": "app(1234)/window[0]/button[@title='Close']",
  "action": "AXPress"
}

返回操作后元素状态，以便您可以验证操作是否有效。

set_value

设置文本字段、复选框、滑块等的值。

参数：

• app （必填）：应用程序名称或PID
• elementPath （必填）：元素路径从 get_ui_tree 或 find_element
• value （必填）：要设置的值（字符串、布尔值或数字，具体取决于元素）

请求示例：

{
  "app": "TextEdit",
  "elementPath": "app(1234)/window[0]/textfield[0]",
  "value": "Hello, world!"
}

返回上一个值、新值和更改后的元素状态。

观察变化

注意应用程序中的UI更改。

参数：

• app （必填）：应用程序名称或PID
• events （可选）：要观看的事件类型(value_changed, focus_changed, window_created, window_destroyed, title_changed).为所有人省略。
• duration （可选）：观察秒数（默认值：30，最大值：300）

请求示例：

{ "app": "TextEdit", "events": ["value_changed"], "duration": 10 }

事件被分批处理，并在持续时间结束时返回。每次观察最多1000个事件。

故障排除

“permission_rejected”错误

未授予访问权限。

1. 打开 系统设置 > 隐私和安全 > 无障碍
2. 添加运行服务器的应用程序（Claude Desktop或您的终端）
3. 授予权限后重新启动应用程序

“app_not_running”错误

应用程序名称与任何正在运行的应用程序都不匹配。使用Dock或Activity Monitor中显示的确切名称。您还可以使用数字PID。

“超时”错误

UI树太大。请减小 depth 参数（尝试1或2）或使用 find_element 取而代之的是特定的标准。

“element_path_error”或“invalid_element”错误

自从获得元素路径后，UI发生了变化。重新运行 get_ui_tree 或 find_element 寻找新的路径。

“blocklistd_application”错误

此应用程序的写入操作被阻止。读取操作仍然有效。请参阅“安全功能”部分以自定义阻止列表。

“只读模式”错误

删除 --read-only 标记或未设置 AXMCP_READ_ONLY.

Claude Desktop无法连接到服务器

• 检查中的二进制路径 claude_desktop_config.json 是正确和绝对的
• 确保二进制文件具有执行权限： chmod +x /path/to/axmcp
• 编辑配置后重新启动Claude Desktop
• 检查Console.app子系统下的日志 com.adamrdrew.axmcp

局限性

• 观察事件是批处理的（在持续时间结束时返回，而不是流式传输）
• 写入操作无法撤消
• 每次观察最多1000个事件，最长持续时间为300秒
• 无交互式确认对话框（MCP协议限制）

发展

运行测试套件：

swift test

此项目使用 乌沙布提 用于迭代开发。看 .ushabti/ 了解阶段计划和进度。

许可证

麻省理工学院