apple-agent-mcp

v0.1.0

Published

a month ago

A maintainable local Apple MCP server for agents, focused on macOS automation with diagnostics and clear tool contracts.

0High
0Medium
0Low

hsien

apple-agent-mcp

English | 中文

面向本地 Agent 的 Apple 应用自动化 MCP 服务。

apple-agent-mcp 让本地 Agent 通过一个长期运行的 localhost 服务访问 macOS 原生数据和 Apple 应用。它当前聚焦 Contacts、Calendar、Reminders、Messages 的有边界、可诊断操作，而不是依赖无边界 AppleScript 扫描或临时脚本。

它能做什么

同时支持 stdio MCP 和 Streamable HTTP MCP。
通过本机 HTTP 服务让多个 Agent 同时调用。
由一个稳定后台进程统一持有 macOS Automation 权限。
所有工具返回统一的 ToolResult，包含明确的 degraded 状态和恢复建议。
提供 Agent / UI / 策略层可消费的 capability manifest。

工具列表

| 工具 | 能力 | 访问类型 | 说明 | | --- | --- | --- | --- | | apple_diagnostics | 检查 macOS 和 Apple 应用可用性 | 读 | 排查权限时优先调用。 | | contacts_search | 按姓名搜索通讯录 | 读 | 返回有边界的联系人摘要。 | | calendar_health | 检查 Calendar Automation 权限 | 读 | 轻量诊断。 | | calendar_upcoming | 读取未来日历事件 | 读 | 通过 daysAhead 和 limit 约束范围。 | | reminders_list | 读取提醒事项 | 读 | 支持 listName 和 completed 过滤。 | | reminders_create | 创建 Apple Reminders 提醒事项 | 写 | “提醒我 / 创建提醒 / 加待办”默认应使用它，而不是通用 cron/timer 工具。 | | messages_health | 检查 Messages Automation 和数据库可读性 | 读 | 会报告完全磁盘访问权限状态。 | | messages_recent_threads | 读取最近 Messages 会话摘要 | 读 | 需要访问 ~/Library/Messages/chat.db。 | | messages_send | 通过 Messages 发送 iMessage/SMS | 写 | 需要明确收件人和正文。 |

当前状态

版本：0.1.0

已实现并完成本机验证：

stdio MCP server
/mcp Streamable HTTP MCP endpoint
/health、/capabilities、/tools/:toolName 本地 HTTP 路由
macOS LaunchAgent 后台部署
非公开 HTTP 路由 Bearer token 保护
Contacts、Calendar、Reminders、Messages 的应用预启动，降低“应用未运行”错误
HTTP MCP 已成功路由 reminders_create 并创建原生 Apple Reminders 提醒事项
parser、AppleScript 执行、HTTP 路由、tool dispatch 单元测试

当前边界：

messages_recent_threads 需要给运行服务的进程授予完全磁盘访问权限。
messages_send 已实现，但只应在提供明确安全测试 handle 后做实发验证。
Calendar 读取有边界，但仍基于 AppleScript；日历数据特别多时可能偏慢。
当前版本不支持创建 Calendar event。

环境要求

macOS
Node.js 22+
npm
OpenClaw、Codex、Agent World UI 或任何 MCP client（如果需要 Agent 集成）

安装

npm install
npm run check
npm run build
npm test

使用 npx

发布到 npm 后，stdio MCP client 可以直接运行：

npx -y apple-agent-mcp

MCP client 配置：

{
  "command": "npx",
  "args": ["-y", "apple-agent-mcp"]
}

这个模式适合单个 client 把 MCP server 作为子进程拉起。

以 stdio MCP 运行

npm run build
node dist/index.js

适合由 MCP client 作为子进程启动的场景。

以本机 HTTP MCP 运行

npm run build
APPLE_AGENT_MCP_TOKEN="replace-with-a-local-secret" npm run start:http

默认 endpoint：

http://127.0.0.1:8765/mcp

本地路由：

| 路由 | 用途 | | --- | --- | | GET /health | 公开运行状态检查。 | | GET /capabilities | capability manifest，需要 Bearer auth。 | | POST /tools/:toolName | 直接 JSON 工具调用，需要 Bearer auth。 | | POST /mcp | 标准 MCP Streamable HTTP endpoint，需要 Bearer auth。 |

直接调用工具的请求体：

{
  "arguments": {
    "limit": 5
  }
}

安装为多 Agent 本机服务

给 OpenClaw、Agent World UI、Codex 或多个本地 Agent 共用时，推荐在这台 Mac 上只运行一个共享 HTTP MCP 服务，所有 Agent 都通过 HTTP 连接它。

发布到 npm 后：

npx -y apple-agent-mcp setup

setup 命令会：

在 ~/.local/share/apple-agent-mcp/runtime 安装稳定本机 runtime
在 ~/.config/apple-agent-mcp/token 创建 token 文件
写入 ~/Library/LaunchAgents/com.apple-agent.mcp.plist
立即启动 LaunchAgent
输出一份 OpenClaw 注册命令作为客户端示例

LaunchAgent 不依赖 OpenClaw 或任何其他 Agent。它会在 macOS 登录时启动，并暴露：

http://127.0.0.1:8765/mcp

生命周期命令：

npx -y apple-agent-mcp status
npx -y apple-agent-mcp restart
npx -y apple-agent-mcp uninstall

LaunchAgent 后台部署

发布到 npm 后优先使用 setup 命令。手工部署时，可以作为用户级 LaunchAgent 运行：

~/Library/LaunchAgents/com.apple-agent.mcp.plist

模板和说明：

scripts/launchd/com.apple-agent.mcp.plist.template
scripts/launchd/README.md
docs/HTTP_LAUNCH_AGENT_DESIGN.md

运行模型：

macOS 登录
  -> LaunchAgent
    -> node dist/cli.js start-http
      -> http://127.0.0.1:8765/mcp
        -> 本地 Agent

建议将 token 放在仓库外，例如：

~/.config/apple-agent-mcp/token

LaunchAgent 应设置：

APPLE_AGENT_MCP_BIND_HOST=127.0.0.1
APPLE_AGENT_MCP_BIND_PORT=8765
APPLE_AGENT_MCP_TOKEN_FILE=/Users/<you>/.config/apple-agent-mcp/token

注册到 OpenClaw

确认 LaunchAgent 已运行后：

TOKEN="$(cat "$HOME/.config/apple-agent-mcp/token")"

openclaw mcp add apple_agent \
  --transport streamable-http \
  --url http://127.0.0.1:8765/mcp \
  --header "Authorization=Bearer $TOKEN" \
  --timeout 30 \
  --parallel

openclaw mcp reload
openclaw mcp probe apple_agent

预期 probe 结果：

apple_agent: 9 tools

OpenClaw 中会出现类似工具名：

apple_agent__reminders_create
apple_agent__calendar_upcoming
apple_agent__contacts_search

为了让 OpenClaw 更稳定地选对工具，应该明确告诉它：“提醒我”“创建提醒”“加待办”默认走 apple_agent__reminders_create，不是通用 cron/timer 工具。当前工具描述中已经包含这条路由提示。

macOS 权限

macOS 权限绑定的是运行 MCP 服务的宿主进程，不是每个 HTTP client。

如果 LaunchAgent 直接启动 Node，需要给 LaunchAgent 使用的 Node binary 授权。未来如果做固定的 .app wrapper，可以让权限身份更稳定。

自动化

以下能力需要 Automation 权限：

Contacts
Calendar
Reminders
Messages 发送 / 健康探测
Apple diagnostics

首次控制每个 Apple 应用时，macOS 会弹出授权提示。

完全磁盘访问权限

以下能力需要完全磁盘访问权限：

messages_recent_threads

原因：

~/Library/Messages/chat.db

中文 macOS 路径：

系统设置 -> 隐私与安全性 -> 完全磁盘访问权限

Messages 历史读取是可选能力。如果暂时不用 Messages 历史，可以不授予完全磁盘访问权限。

Capability Manifest

静态 capability manifest：

capabilities/apple-agent-mcp.capabilities.v1.json

HTTP 服务运行后：

GET http://127.0.0.1:8765/capabilities

manifest 描述：

工具名称和领域
读写风险级别
所需 macOS 权限
验证状态
给 Agent World / OpenClaw 类客户端使用的 UI affordance hints

开发

npm run dev        # stdio MCP
npm run dev:http   # HTTP MCP
npm run check
npm run build
npm test

项目结构：

src/
  index.ts                 # stdio MCP 入口
  http-server.ts           # HTTP server 入口
  server/
    mcp.ts                 # 共享 MCP server factory
    http.ts                # HTTP 路由和 Streamable HTTP transport
  core/
    appleScript.ts         # osascript 执行与 timeout 清理
    macApps.ts             # LaunchServices 应用预启动
    result.ts              # ToolResult 结构
  adapters/
    contacts/
    messages/
    calendar/
    reminders/
  scripts/applescript/     # 外置 AppleScript builder
  tools/
    definitions.ts
    registry.ts

安全说明

只绑定 127.0.0.1。
所有非公开路由都要求 Bearer auth。
token 必须放在仓库外。
不要提交包含 Authorization header 的 OpenClaw 本地配置。
messages_send 和 reminders_create 属于写操作，上层客户端应做用户确认。

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

apple-agent-mcp

它能做什么

工具列表

当前状态

环境要求

安装

使用 npx

以 stdio MCP 运行

以本机 HTTP MCP 运行

安装为多 Agent 本机服务

LaunchAgent 后台部署

注册到 OpenClaw

macOS 权限

自动化

完全磁盘访问权限

Capability Manifest

开发

安全说明

相关文档