AI导哈

macOS AI代理控制服务器

一个原生macOS服务器，通过MCP协议为AI代理提供对Mac的深度控制功能，包括屏幕截图、系统控制、应用脚本和UI自动化等29种工具。

  • by jcanizalez
  • Swift
  • 本地部署
  • 更新于
在 GitHub 查看 jcanizalez/macos-mcp-server

使用说明

macOS MCP服务器

原生macOS MCP（模型上下文协议） 服务器，使AI代理能够深度控制您的Mac。仅使用Apple框架内置Swift，除此之外没有第三方依赖 MCP-SDK.

29工具 分为4类：屏幕截图、可访问性/UI自动化、系统控制和应用程序脚本。

安装

自制（推荐）

brew install jcanizalez/tap/macos-mcp-server

从源代码构建

需要Xcode 15+和macOS 13+。

git clone https://github.com/jcanizalez/macos-mcp-server.git
cd macos-mcp-server
swift build -c release
# Binary at .build/release/macos-mcp-server

下载二进制文件

获取最新版本 GitHub 发布.

设置

1.授予权限

服务器需要两个macOS权限才能工作：

  • 无障碍：系统设置>隐私和安全>辅助功能
  • 屏幕录制：系统设置>隐私和安全>屏幕录制

将二进制文件（或承载它的应用程序，如Claude Desktop或您的终端）添加到这两个列表中。

2.配置您的MCP客户端

克劳德桌面版 (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "macos": {
      "command": "macos-mcp-server"
    }
  }
}

克劳德代码:

claude mcp add macos-mcp-server -- macos-mcp-server

自定义集成 （stdio传输，换行符分隔的JSON）：

# The server communicates via stdin/stdout using JSON-RPC 2.0
macos-mcp-server

工具

屏幕截图和显示（3个工具）

工具 说明
macos_list_windows 列出所有可见的窗口，包括应用程序名称、标题、ID和边界
macos_screenshot_window 捕获特定应用程序窗口的屏幕截图（即使在其他窗口后面）
macos_screenshot_screen 捕捉全屏或特定区域

应用程序和系统（5个工具）

工具 说明
macos_app_list_running 列出所有正在运行的应用程序，包括捆绑包ID、PID和活动状态
macos_app_activate 将应用程序放在前面（如果未运行，则启动它）
macos_spotlight_search 使用Spotlight搜索文件（支持 kind:pdf, name:*.swift，自由文本）
macos_notification_send 发送带有标题、正文和可选声音的macOS通知
macos_system_info 操作系统版本、CPU、内存、磁盘、电池、热状态、活动应用程序

剪贴板（2个工具）

工具 说明
macos_clipboard_read 读取当前剪贴板文本
macos_clipboard_write 将文本写入剪贴板

可访问性和UI自动化（11个工具）

所有辅助工具都使用苹果的原生 AXUIElement API和 CGEvent 用于输入合成。

工具 说明
macos_ax_check_permission 检查/请求辅助功能权限
macos_ax_list_elements 列出带有角色、标题、框架的UI元素（按钮、字段、菜单）
macos_ax_find_element 按角色、标题或标识符查找元素
macos_ax_click 按元素（AXPress）或屏幕坐标（CGEvent）单击
macos_ax_type_text 通过CGEvent按键或AXValue设置键入文本
macos_ax_press_key 按组合键（Cmd+C、Shift+Tab、F5等）
macos_ax_scroll 在特定位置向任何方向滚动
macos_ax_drag 从一个点平滑拖动到另一个点
macos_ax_get_focused_element 获取当前聚焦的元素及其属性
macos_ax_get_mouse_position 获取当前鼠标光标坐标
macos_ax_element_at_position 识别给定屏幕坐标处的UI元素

系统控制（8个工具）

使用CoreAudio、CoreWLAN、IOKit和NSWorkspace进行深度操作系统集成。

工具 说明
macos_open_url 在默认应用程序中打开URL、文件或文件夹（支持自定义方案）
macos_audio_volume 获取/设置音量、静音/取消静音（CoreAudio）
macos_dark_mode 获取/设置/切换暗模式
macos_display_brightness 获取/设置显示器亮度（IOKit）
macos_wifi_info SSID、信号强度、速度、安全性、信道（CoreWLAN）
macos_file_info 文件元数据：大小、日期、权限、类型、扩展属性
macos_run_applescript 执行AppleScript以实现Safari自动化、应用程序脚本编写等。
macos_default_app 获取文件类型或URL方案的默认应用程序

使用技巧

在浏览器中单击web内容

AX工具在原生macOS UI（按钮、菜单、文本字段）方面表现出色。对于浏览器内容：

  1. 使用 macos_ax_element_at_position 在单击之前验证坐标处的内容
  2. 使用 macos_run_applescript 对于Safari自动化：
tell application "Safari"
    do JavaScript "document.querySelector('a.my-link').click()" in current tab of front window
end tell
  1. 点击工具现在会报告哪个元素被点击了，这样你就可以得到关于准确性的反馈

导航应用程序

-- Best: use open_url for file/folder/URL navigation
macos_open_url: { "url": "https://github.com" }
macos_open_url: { "url": "/Users/me/Documents" }

-- Use keyboard shortcuts for app-specific actions
macos_ax_press_key: { "key": "t", "modifiers": ["cmd"] }       // New tab
macos_ax_press_key: { "key": "l", "modifiers": ["cmd"] }       // Focus address bar
macos_ax_press_key: { "key": "c", "modifiers": ["cmd"] }       // Copy

通过点击协调屏幕截图

1. macos_screenshot_window  -- See what's on screen
2. macos_ax_element_at_position  -- Verify target at coordinates
3. macos_ax_click  -- Click with hit feedback

建筑

Sources/MacOSMCPServer/
  main.swift                    -- Entry point, MCP server setup
  Helpers/
    ToolRegistry.swift          -- Tool dispatch, ToolModule protocol
    ProcessRunner.swift         -- Shell command execution
  Tools/
    ScreenshotTools.swift       -- CGWindowListCreateImage, window capture
    ClipboardTools.swift        -- NSPasteboard read/write
    AppTools.swift              -- NSWorkspace app management
    SpotlightTools.swift        -- MDQuery/mdfind search
    NotificationTools.swift     -- osascript notifications
    SystemInfoTools.swift       -- ProcessInfo, IOKit battery
    AccessibilityTools.swift    -- AXUIElement, CGEvent (11 tools)
    SystemControlTools.swift    -- CoreAudio, CoreWLAN, IOKit (8 tools)

每个工具组都是一个 ToolModule 枚举 tools （定义）和 handle() （派遣）。这 ToolRegistry 聚合所有模块和路由MCP tools/call 请求：

需求

  • macOS 13（Ventura）或更高版本
  • Xcode 15+（用于从源代码构建）
  • 可访问性和屏幕录制权限

许可证

麻省理工学院

相关 MCP