macOS-MCP

🍎 macOS-MCP

概述

macOS-MCP 是一款轻量级、开源的模型上下文协议服务，可连接 AI Agent 与 macOS 操作系统。它支持通过大模型无缝自动化操作 macOS，涵盖文件导航、应用控制、UI 交互、浏览器自动化和系统操作等任务。

支持的操作系统

• macOS 12（Monterey）
• macOS 13（Ventura）
• macOS 14（Sonoma）
• macOS 15（Sequoia）
• macOS 26（Tahoe）

主要功能

• 兼容任何大模型（可选视觉能力）
  与传统自动化工具不同，macOS-MCP 无需计算机视觉、微调模型或专门配置。可与 Claude、GPT、Gemini 或其他大模型无缝协作。

• 原生集成 macOS
  使用辅助功能 API 原生交互 macOS UI 元素。无需变通方案即可打开应用、控制窗口、模拟用户输入并捕获桌面状态。

• 丰富的自动化工具集
  提供完整的工具集，支持键盘和鼠标操作、窗口管理、UI 状态捕获、从辅助功能树提取交互元素，以及执行 AppleScript。

• 轻量且开源
  依赖精简，完整源代码基于 MIT 许可证开放。易于设置和部署。

• 智能上下文感知
  自动检测应用状态（Launchpad、Control Center、Spotlight）。智能扫描菜单栏、程序坞、桌面和系统 UI 元素。

• 可定制且可扩展
  可轻松扩展自定义工具或修改行为，以满足特定的自动化需求。

安装

前置条件

• Python：3.11 或更高版本
• UV 包管理器：使用 pip install uv 或 curl -LsSf https://astral.sh/uv/install.sh | sh 安装
• macOS：12（Monterey）或更高版本
• 辅助功能权限：与 UI 元素交互时需要

快速开始

直接运行服务：

uvx macos-mcp serve

# Or with SSE/Streamable HTTP for network access
uvx macos-mcp serve --transport sse --host localhost --port 8000
uvx macos-mcp serve --transport streamable-http --host localhost --port 8000

将其作为后台服务运行，使其立即启动并在每次登录时启动：

macos-mcp install

# Or choose the HTTP transport and bind address explicitly
macos-mcp install --transport sse --host 127.0.0.1 --port 8000

这会在 ~/Library/LaunchAgents/com.macos-mcp.server.plist 安装一个 launchd 启动代理。 使用 macos-mcp uninstall 将其移除。日志写入 ~/.macos-mcp/server.log 和 ~/.macos-mcp/server.error.log。

传输选项

授予所需权限

macOS-MCP 需要辅助功能和屏幕录制权限才能正常运行。

辅助功能权限

1. 打开 系统设置 → 隐私与安全性 → 辅助功能
2. 点击锁形图标并进行身份验证
3. 添加以下应用程序：
   • 你的终端应用程序（Terminal、iTerm2、VS Code 等）
   • Python（通常为 /usr/bin/python3 或由 UV 管理的 Python 版本）
   • UV（如果在本地安装，则为 ~/.local/bin/uv；否则为 UV 管理的 Python 环境）
4. 授予权限后重启终端

对于 uvx 用户： 为你的终端应用程序和 Python 授予权限，因为 uvx 会从 UV 的缓存中运行 Python 包。

如果解释器二进制文件在“+”选择器中显示为灰色／无法选择（这是 UV 管理的 Python 符号链接的已知问题，例如 .venv/bin/python3.12 → ~/.local/share/uv/python/...）：不要尝试手动添加。只需启动服务即可——从 v0.3.10 起，它会在启动时使用 prompt 选项调用 AXIsProcessTrustedWithOptions，请求 macOS 显示原生授权对话框，并为你自动注册正在运行的进程。批准该对话框，然后重启服务。

如果你的进程是由已获得辅助功能权限的父进程作为子进程启动（例如某些 Claude Desktop 配置），并且权限检查仍错误地失败，请设置 MACOS_MCP_SKIP_PERMISSION_CHECK=1，将检查降级为警告，而不是退出。

屏幕录制权限

Snapshot 工具需要屏幕录制权限才能截取屏幕截图：

1. 打开 系统设置 → 隐私与安全性 → 屏幕录制
2. 点击锁形图标并进行身份验证
3. 添加与上述相同的应用程序（终端、Python、UV）
4. 授予权限后重启终端

注意： 如果 Snapshot 工具运行失败，请在系统设置中确认已授予这两项权限。

集成选项

{
  "mcpServers": {
    "macos-mcp": {
      "command": "uvx",
      "args": ["macos-mcp", "serve"]
    }
  }
}

macos-mcp install --transport streamable-http --host 127.0.0.1 --port 8000

{
  "mcpServers": {
    "macos-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://127.0.0.1:8000/mcp",
        "--transport",
        "http-only"
      ]
    }
  }
}

# Start server with an auth key
macos-mcp install --transport streamable-http --host 0.0.0.0 --port 8000 \
  --auth-key "your-secret-token"

{
  "mcpServers": {
    "macos-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://127.0.0.1:8000/mcp",
        "--transport",
        "http-only",
        "--header",
        "Authorization: Bearer your-secret-token"
      ]
    }
  }
}

npm install -g @google/gemini-cli

{
  "theme": "Default",
  "mcpServers": {
    "macos-mcp": {
      "command": "uvx",
      "args": ["macos-mcp", "serve"]
    }
  }
}

pi install git:github.com/CursorTouch/MacOS-MCP

/reload

pi -e git:github.com/CursorTouch/MacOS-MCP

git clone https://github.com/CursorTouch/MacOS-MCP.git
cd MacOS-MCP
uv sync
npm install
pi

export MACOS_MCP_ROOT=/path/to/MacOS-MCP

git clone https://github.com/CursorTouch/MacOS-MCP.git
cd MacOS-MCP
uv sync
tau

export MACOS_MCP_ROOT=/path/to/MacOS-MCP

MCP 工具

macOS-MCP 为桌面自动化提供了一套全面的工具：

限制

• 辅助功能要求：需要在系统设置中手动授予权限
• 应用兼容性：部分应用对 Accessibility API 的支持有限或不支持
• 性能差异：包含许多元素的复杂 UI 可能需要较长的遍历时间
• 文本输入：某些专用输入字段可能无法正确接收按键
• 身份验证：无法与系统身份验证对话框交互

安全与访问控制

身份验证

macos-mcp serve --transport sse --host 0.0.0.0 --auth-key "your_token"

所有请求都必须包含 Authorization: Bearer your_token 请求头。

IP 允许列表

macos-mcp serve --auth-key "token" --ip-allowlist "203.0.113.0/24,198.51.100.5"

将连接限制为指定的 CIDR 范围。

TLS/HTTPS

openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes

macos-mcp serve --ssl-certfile cert.pem --ssl-keyfile key.pem

OAuth 2.0 + PKCE

对于使用 OAuth（例如 Claude Desktop）而非静态 API 密钥的 MCP 客户端：

macos-mcp serve --transport streamable-http --host 0.0.0.0 \
  --ssl-certfile ~/.macos-mcp/cert.pem \
  --ssl-keyfile  ~/.macos-mcp/key.pem \
  --oauth-client-id my-client \
  --oauth-client-secret my-secret

Claude Desktop 配置（通过 mcp-remote 桥接程序 — 参见集成选项）：

{
  "mcpServers": {
    "macos-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://<host>:8000/mcp",
        "--transport",
        "http-only"
      ]
    }
  }
}

注意： Claude Desktop 的 claude_desktop_config.json 不直接支持 "type": "http" 或 "url" 条目。请按上文所示使用 mcp-remote， 或在 Claude Desktop UI 中通过 Settings → Connectors → Add custom connector 添加服务。

OAuth 服务提供以下端点：

• GET /.well-known/oauth-authorization-server — 服务元数据（RFC 8414）
• GET /oauth/authorize — Authorization Code + PKCE（必须使用 S256）
• POST /oauth/token — 令牌交换（需要客户端密钥）
• POST /oauth/register — 已禁用；客户端必须预先配置

动态客户端注册已禁用。重定向 URI 只能使用回环 http(s)。 身份验证密钥和 OAuth 可以同时使用 — 两者都可作为有效的 Bearer 令牌。

SSRF 防护

Scrape 工具会阻止：私有 IP、回环地址、链路本地地址、URL 中的凭据以及非 HTTP 协议。

配置文件（~/.macos-mcp/config.toml）

无需每次都传入标志，可将配置保存到 ~/.macos-mcp/config.toml。CLI 标志始终会覆盖配置文件中的值。

搜索顺序：

1. --config /path/to/config.toml
2. ~/.macos-mcp/config.toml

stdio — 仅限本地使用，无需安全配置：

[server]
transport = "stdio"

SSE — 网络访问，需配置身份验证和 IP 限制：

[server]
transport = "sse"
host      = "0.0.0.0"
port      = 8000
auth_key  = "your-secret-key"

[security]
ip_allowlist = ["192.168.1.0/24"]

Streamable HTTP — 网络访问，需配置身份验证和 TLS（生产环境推荐）：

[server]
transport    = "streamable-http"
host         = "0.0.0.0"
port         = 8000
auth_key     = "your-secret-key"
ssl_certfile = "cert.pem"   # resolved relative to ~/.macos-mcp/
ssl_keyfile  = "key.pem"

[security]
ip_allowlist        = ["192.168.1.0/24"]
oauth_client_id     = "my-client"      # optional — enables OAuth 2.0 + PKCE
oauth_client_secret = "my-secret"

[tools]
exclude = ["Shell", "Scrape"]   # disable specific tools

可用工具名称：App、Shell、Snapshot、Click、Type、Scroll、Move、Shortcut、Wait、Scrape、Notification

将证书和密钥文件放在同一目录中：

~/.macos-mcp/
├── config.toml
├── cert.pem
└── key.pem

直接在该目录中生成自签名证书：

mkdir -p ~/.macos-mcp
openssl req -x509 -newkey rsa:4096 \
  -keyout ~/.macos-mcp/key.pem \
  -out ~/.macos-mcp/cert.pem \
  -days 365 -nodes

环境变量

所有变量均为可选。通过 claude_desktop_config.json 中的 env 键进行设置。

claude_desktop_config.json 示例（带身份验证和 TLS 的远程配置）：

{
  "mcpServers": {
    "macos-mcp": {
      "command": "uvx",
      "args": ["macos-mcp", "serve", "--transport", "sse", "--host", "0.0.0.0"],
      "env": {
        "MACOS_MCP_AUTH_KEY": "your_token",
        "MACOS_MCP_IP_ALLOWLIST": "203.0.113.0/24",
        "MACOS_MCP_SSL_CERTFILE": "/path/to/cert.pem",
        "MACOS_MCP_SSL_KEYFILE": "/path/to/key.pem"
      }
    }
  }
}

遥测

macOS-MCP 会收集匿名使用情况数据，以帮助改进服务。不会跟踪任何个人信息、工具参数或输出。

如需禁用遥测，请将 ANONYMIZED_TELEMETRY 设置为 false：

{
  "mcpServers": {
    "macos-mcp": {
      "command": "uvx",
      "args": ["macos-mcp", "serve"],
      "env": { "ANONYMIZED_TELEMETRY": "false" }
    }
  }
}

安全

⚠️ 重要安全提示：macOS-MCP 拥有完整的辅助功能 API 权限，并且在未进行沙盒隔离的情况下执行真实的系统操作。它可以执行永久且不可逆的操作。

使用 macOS-MCP 前：

• ✅ 仅向可信应用授予辅助功能权限
• ✅ 了解 Shell 命令会以完整的用户权限执行
• ✅ 执行前检查 AI 生成的操作计划
• ✅ 仅在数据无价值的虚拟机或隔离环境中使用
• ✅ 在类似生产环境的场景中测试前创建备份

⛔ 请勿用于：

• 存有不可替代数据的系统
• 生产机器或共享系统
• 受合规法规约束的环境（HIPAA、PCI 等）

详细的安全指南请参阅 SECURITY.md。

贡献

欢迎贡献！请参阅 CONTRIBUTING.md，了解以下内容：

• 开发环境设置和代码标准
• 测试要求
• 拉取请求流程
• 编码规范（Ruff 格式化，行长为 100 个字符）

许可证

macOS-MCP 根据 MIT 许可证授权，详情请参阅 LICENSE。

致谢

macOS-MCP 基于以下优秀的开源项目构建：

• PyObjC - Python 到 Objective-C 的桥接
• Pillow - Python 图像库
• FastMCP - MCP 框架
• macOS 辅助功能 API（ApplicationServices）

引用

如果您在研究或项目中使用 macOS-MCP，请引用：

@software{macos-mcp,
  author       = {Jeomon George},
  title        = {macOS-MCP: Lightweight MCP Server for macOS Automation},
  year         = {2025},
  publisher    = {GitHub},
  url          = {https://github.com/Jeomon/macos-mcp}
}

有问题或遇到故障？提交问题，或查看 SECURITY.md 了解安全相关事项。