mailappmcp (Aernouddekker)

macos mcp

没有API密钥，没有OAuth，没有云服务。通过AppleScript和URL方案直接与macOS应用程序对话(tel://, facetime://).在Mac上本地运行。

CUPS打印(printmcp)曾经住在这里；它移动到 办公室mcp 因为它是一个shell包装器，而不是AppleScript桥。

服务器

邮件(mailappmcp)--21个工具

适用于Mail.app中配置的每个电子邮件帐户——iCloud、Gmail、Outlook、Fastmail，应有尽有。

数字(numbersmcp)--29个工具

适用于任何打开的数字电子表格。

联系人(@aernoud/contactsmcp)--15个工具

与系统通讯簿配合使用——所有帐户都同步到Contacts.app。

日历(calendarmcp)--25个工具

适用于calendar.app中配置的每个日历——iCloud、谷歌、Exchange、本地，应有尽有。

提醒事项(@aernoud/remindersmcp)--22个工具

适用于Reminders.app中配置的每个提醒列表——iCloud、Exchange、本地、你能想到的。

FaceTime(facetimemcp)--3个工具

通过将URL方案传递给以下对象来发起调用 open。电话呼叫需要通过Continuity配对的iPhone（因此macOS可以通过手机路由）。

电话号码被标准化+验证为E.164(+15551234567)；空格、破折号和括号是可以容忍的。macOS可能会在拨号前显示确认提示——根据设计，没有完全静音的拨号路径。

需求

• macOS（使用AppleScript，无法在Linux/Windows上运行）
• Node.js 18+

安装

来自npm

npm install -g mailappmcp            # Mail server
npm install -g numbersmcp            # Numbers server
npm install -g @aernoud/contactsmcp  # Contacts server
npm install -g @aernoud/calendarmcp  # Calendar server
npm install -g @aernoud/remindersmcp # Reminders server
npm install -g @aernoud/facetimemcp  # FaceTime / phone calls

来源

git clone https://github.com/aernouddekker/macos-mcp.git
cd macos-mcp
npm install
npm run build

配置

克劳德代码

添加 ~/.claude/settings.json 或者你的项目 .mcp.json:

{
  "mcpServers": {
    "mailappmcp":   { "command": "npx", "args": ["-y", "mailappmcp"] },
    "numbersmcp":   { "command": "npx", "args": ["-y", "numbersmcp"] },
    "contactsmcp":  { "command": "npx", "args": ["-y", "@aernoud/contactsmcp"] },
    "calendarmcp":  { "command": "npx", "args": ["-y", "@aernoud/calendarmcp"] },
    "remindersmcp": { "command": "npx", "args": ["-y", "@aernoud/remindersmcp"] },
    "facetimemcp":  { "command": "npx", "args": ["-y", "@aernoud/facetimemcp"] }
  }
}

克劳德桌面/协作

添加 ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "mailappmcp":   { "command": "npx", "args": ["-y", "mailappmcp"] },
    "numbersmcp":   { "command": "npx", "args": ["-y", "numbersmcp"] },
    "contactsmcp":  { "command": "npx", "args": ["-y", "@aernoud/contactsmcp"] },
    "calendarmcp":  { "command": "npx", "args": ["-y", "@aernoud/calendarmcp"] },
    "remindersmcp": { "command": "npx", "args": ["-y", "@aernoud/remindersmcp"] },
    "facetimemcp":  { "command": "npx", "args": ["-y", "@aernoud/facetimemcp"] }
  }
}

运作原理

每台服务器都通过stdio在本地运行。邮件、号码和联系人服务器构建AppleScript字符串，并通过以下方式执行它们 osascript，并将结构化输出解析回JSON。打印服务器向CUPS发送外壳(lp, lpstat, lpoptions, cancel)；FaceTime服务器 tel:// / facetime:// URL指向 open.共享包(@mailappmcp/shared)提供AppleScript运行器、通用命令运行器(runCommand)、字符串转义和基于分隔符的解析。

应用程序生命周期——保持原样

邮件、日历、联系人和提醒需要运行各自的应用程序来响应AppleScript。每个服务器在首次使用时自动启动这些应用程序，并在之后进行清理，而不是要求您保持这些应用程序打开：

• 在第一个触及应用程序的工具调用中，服务器检查（通过 pgrep)应用程序是否已在运行。如果没有，它将在后台启动它(open -g -a)在不窃取焦点的情况下，在运行该工具之前，等待应用程序接受AppleEvents最多5秒。
• 该状态在进程中被记住 在MCP服务器的生命周期内。随后对同一应用程序的工具调用跳过探测并重用正在运行的应用程序——没有重复的启动惩罚。
• 服务器关闭时 （SIGTERM/SIGINT/SIGHUP/normal exit——例如，当Claude Desktop断开服务器连接或聊天结束时），服务器仅退出应用程序 它启动了。服务器启动前打开的应用程序将保持原样。
• 边缘情况：如果服务器被强制终止(SIGKILL)，退出处理程序无法运行，因此任何自动启动的应用程序都会保持运行。就像你从来没有服务器一样。

这意味着你可以使用这些工具，而不必担心会话后会有一堆半启动的应用程序挥之不去，也不必担心服务器会杀死你正在使用的应用程序。

安全

• compose-message 打开一个可见的草稿——您在发送前进行审核
• send-message 是一个单独的、明确的动作
• reply-to-message 和 forward-message 默认为草稿模式(sendImmediately: false)
• delete-messages 移动到回收站（标准Mail.app行为）

HTML电子邮件

compose-message 和 send-message 接受可选 htmlBody 参数。提供后，邮件将创建为富文本/HTML邮件，收件人将看到呈现的格式（标题、粗体、列表、可点击链接），而不是原始标签。 body 仍然是必需的，并且用作读取纯文本内容的客户端的纯文本回退。省略 htmlBody 对于现有的纯文本行为——完全向后兼容。

// send-message with HTML body
{
  "to": ["alice@example.com"],
  "subject": "Weekly update",
  "body": "Highlights:\n- Shipped feature X\n- Fixed bug Y",
  "htmlBody": "
Highlights

Shipped feature X

Fixed bug Y — see #42

"
}

在幕后，HTML路径使用JXA(osascript -l JavaScript)以及Mail.app的运行时 htmlContent 外发消息的设置器。纯文本路径仍然使用普通的AppleScript。

已知限制

通用

• osascript 每次通话有30秒的超时时间
• 应用程序在首次使用时会自动启动，如果之前没有运行，则会在服务器关闭时退出——请参阅 应用程序生命周期

邮件

• content contains AppleScript中的搜索在大型邮箱上可能很慢——默认情况下，邮件服务器搜索主题和发件人

数字

• 数字工具需要打开文档

日历

这些是Calendar.app的AppleScript接口本身的限制，而不是MCP服务器的限制：

• 日历不能通过AppleScript删除。 delete calendar 提高 -10000 （AppleEvent处理程序失败）在每个现代macOS版本上。这 delete-calendar 该工具检查日历是否存在，然后返回一个描述性错误——您必须从calendar.app侧栏中手动删除日历（右键单击→ 删除）。
• 日历没有可用的id/uid。 日历.app的 calendar 类不通过AppleScript公开稳定的id(uid of 提高 -10000).因此，所有日历工具都通过以下方式识别日历 名字 --确保你的日历名称是唯一的。
• whose 事件过滤器为O（n）。 AppleScript扫描日历中的每个事件以进行评估 whose start date ≥ X 谓词。在繁忙的多日历商店中，即使对所有日历进行为期7天的空查询，也可能需要60多秒，甚至超过30秒 osascript 超时。 总是通过a calendarName 到 list-events, search-events, today-events，以及 upcoming-events 在可能的情况下 以确定扫描范围。 search-events 另外强制执行日期窗口（默认值：-30天至+365天）。
• move-event 重新分配uid。 Calendar.app无法恢复日历之间的事件。该工具删除源事件并在目标日历中创建一个新事件；新事件有一个新的uid（返回为 newUid 旁边 oldUid).
• 重复显示为原始RRULE字符串 （例如。 FREQ=WEEKLY;INTERVAL=1)--只读和写，不解析或扩展。

许可证

麻省理工学院