iconnect

AirMCP

你的 AI 助手可以使用你平时使用的 Mac 应用。 用通俗的语言提出需求，AirMCP 就会在你设备上的真实 Notes、Mail、Calendar、Reminders、Messages、Photos、Safari、Finder 和 Shortcuts 中执行操作——使用的是你的真实数据，不是副本，也不是沙盒。macOS 运行时现已推出；iOS 运行时正处于预览阶段。

发布状态（2026-10-27 KST）： v2.16.7 已通过 npm 和 MCPB 扩展提供。macOS 应用 ZIP 仍不可用，因为 Apple 公证认证失败。请使用 CLI 或 MCPB 方式；已完成的检查和剩余的应用分发关卡，请参见发布验证记录。

"Brief me on today's calendar, overdue reminders, and unread mail."
"For my next meeting, pull up the related notes, contacts, files, and reminders."
"Search my Safari tabs for that article and save a summary to Notes."
"Draft replies to the urgent mail, but ask me before sending anything."
"Run my Morning Routine shortcut."

在 macOS 上使用 Node.js 20+ 开始：

npx airmcp init

然后向你的客户端提出需求。可与 Claude、Codex、Cursor、Raycast、Xcode agents 及其他任何 MCP 客户端搭配使用。在你选择启用之前，不会读取或更改客户端设置。

更多内容：常见工作流 · 所有工具 · 快速入门

它不会背着你采取行动

AirMCP 是连接器和控制层，而不是另一个 Agent。破坏性调用会在执行前预览，每次调用都需单独批准，审计链具有防篡改能力且可供你验证——读取 airmcp://trust 并自行检查。详情请参阅安全模型。

由 scripts/demo/governed-flow.mjs 根据真实的本地 MCP 往返生成——真实的终端输出，并非预先编排的对话记录。

多语言项目页面：heznpc.github.io/AirMCP

你将获得

• Apple 工作区工具，涵盖 Notes、Reminders、Calendar、Contacts、Mail、 Messages、Music、Finder、Safari、Photos、Shortcuts、系统控制、屏幕 截取、Weather、Maps、Location、Bluetooth 等。
• Google Workspace 工具，涵盖 Gmail、Drive、Sheets、Calendar、Docs、Tasks、 People，以及原始 gws CLI 访问能力。
• 配置档案和渐进式暴露，让客户端从精简的入口开始，而不是一开始就加载所有工具。
• Skills DSL 工作流，支持 parallel、loop、retry、on_error、运行时 输入和事件触发器。
• App Intent 操作桥接，根据 MCP 清单生成，供 macOS Shortcuts 使用；还提供仅适用于 iOS 的 App Shortcuts 提供程序，并单独控制破坏性意图。
• 原生 Swift 桥接，支持 EventKit、PhotoKit、HealthKit、Vision、设备端 语义搜索和 FoundationModels 预览版构建。AirMCP.app 内置标准桥接；npm 和 MCPB 用户可 按需单独构建，且不必安装。
• 双传输方式：stdio 适用于标准 MCP 客户端；HTTP/SSE 适用于共享的本地运行时、浏览器客户端、注册表和常驻主机。

Apple 平台方向

AirMCP 是一个统一治理的操作层，并为不同平台分配不同角色，而不是在每台设备上复制完整的 Mac 运行时。

平台	状态	角色
macOS	可用	完整的本地 MCP 运行时，以及广泛的 Apple 应用和系统集成。
iOS / iPadOS	预览版	原生的日历、提醒事项、通讯录、健康和位置操作，以及进程内 AppIntents。
visionOS	路线图	空间交互和原生操作；仅适用于 Mac 的自动化则通过 Mac 路由。
watchOS	路线图	通过配对的 iPhone 运行时执行命令、接收通知，并逐次调用审批。

共享的 Swift 和 AppIntents 层是可移植性的边界。平台的沙盒和生命周期规则仍会决定哪些操作在本地运行，哪些路由到配对的 Mac 或 iPhone。

快速开始

Claude Desktop 一键安装

1. 从 Releases 下载 airmcp-<version>.mcpb。
2. 将它拖到 Claude Desktop 上，或使用 Settings -> Extensions -> Install from file...。
3. 在安装表单中选择模块并完成设置。

完整指南：docs/mcpb.md。

macOS 应用（已签名并完成公证）

桌面发行版是经过 Developer ID 签名、公证并附加公证票据的 AirMCP-<version>.zip。选择此方式前，请在 Releases 中检查所选版本的资源： v2.16.6 和 v2.16.7 没有应用 ZIP。v2.16.7 的尝试止步于 Apple 公证账户身份验证；其应用发行版并不完整。该 ZIP 无需构建步骤：其中包含嵌入式 Node 运行时、Swift 桥接层、菜单栏信任中心，以及生成的 App Intents（Shortcuts 操作）和小组件。

请选择附带应用 ZIP 的 v2.16.5 或更高版本。v2.16.3 和 v2.16.4 发行版附带的应用 ZIP 签名、公证和票据附加均正常，但启动时会在菜单栏图标出现前崩溃——这是已在 v2.16.5 中修复的资源包路径错误。

1. 下载 AirMCP-<version>.zip 并解压。
2. 将 AirMCP.app 移至 /Applications 并打开。由于公证票据已附加，即使离线，Gatekeeper 也会接受它。
3. 按照以同意为导向的设置窗口操作；在你选择客户端之前，不会启动任何内容，也不会编辑任何客户端的设置。

CLI 向导

安装 Node.js 20+，然后运行：

npx airmcp init

向导会选择一个配置方案，并将偏好设置保存在 ~/.config/airmcp/config.json 中。注册客户端是单独的同意步骤，默认选择为 No；在你选择加入之前，不会读取或更改 Claude、Codex、Cursor 或 Windsurf 的任何设置。

对于 Codex、Claude Code、Cursor、Windsurf 和其他 stdio 客户端，请使用直接运行时；也可以先安装发行版中包含的已签名 AirMCP-<version>.zip，然后使用由应用管理的运行时：

npx airmcp init --no-clients
npx airmcp connect-clients --client-runtime direct --dry-run
npx airmcp connect-clients --client-runtime direct

只有在安装该已签名的应用 ZIP 并明确选择 Start Local Runtime 后，由应用管理的运行时才可用。v2.16.5 之前的发行版没有应用资源，或者其应用无法启动；不要将客户端配置为在这些版本上等待 AirMCP.app。

非交互式示例：

npx airmcp init --profile starter --yes
npx airmcp init --profile communications-safe --yes
npx airmcp init --profile productivity --yes
npx airmcp init --profile productivity --yes --connect-clients
npx airmcp init --profile productivity --yes --connect-clients --client-runtime direct

检查安装情况：

npx airmcp doctor

常见工作流

连接后，使用自然语言向 MCP 客户端提问：

• “告诉我今天的日历活动和逾期提醒事项。不要更改任何内容。”
• “简要介绍今天的日历、逾期提醒事项、未读邮件和最近的笔记。”
• “将今天的会议整理成准备事项清单。”
• “为紧急邮件拟写回复，但发送前先征求我的同意。”
• “为我的下一场会议查找相关笔记、联系人、文件和提醒事项。”
• “在我的 Safari 标签页中搜索那篇文章，并将摘要保存到备忘录。”
• “运行我的 Morning Routine 捷径。”
• “截取屏幕并保存到桌面。”

更多工作流示例请参阅 docs/workflows.md。

运行时模型

AirMCP 旨在让大量本地能力保持可用，同时避免将完整目录加载到每个客户端上下文中。

当前完整的生成目录包含 32 个模块中的 293 个工具。 配置档案和渐进式开放功能可避免客户端一次性加载全部内容。

• 配置档案：starter、communications-safe、productivity、full 或 custom。
• 工具开放方式：progressive、profile 或 full。
• 模块包：使用 npx airmcp modules 或 AIRMCP_MODULE_PACKS=core,productivity，仅启用所需的模块包。
• 任务会话：start_tool_session、discover_tools 和 run_tool 可让宽泛的运行时表现得像面向特定任务的精简工具集。
• 选择加入的网络模块：所有配置档案中的 webhooks 和 powerautomate 均默认关闭，只有明确启用后才会开启。

实用命令：

npx airmcp modules
npx airmcp modules enable productivity --install
npx airmcp --full
npx airmcp workflows
npx airmcp workflows --readiness
npx airmcp workflows today-overview --prompt

today-overview 是适合入门的安全首个工作流：它仅读取 Calendar 和 Reminders，绝不写入数据。将打印出的提示词粘贴到已连接的 MCP 客户端中，即可在客户端授权和 AirMCP 审计覆盖下进行受治理的首次运行。

workflows <id> --preview 是单独的本地诊断功能。它直接读取 Apple 应用， 绕过 MCP 治理路径，且不会创建 AirMCP 审计记录； 请勿将其用作首次成功运行的工作流。范围更广的诊断功能，例如 daily-briefing --preview，会在读取实时数据之前报告缺失的模块。

完整的生成工具清单位于 docs/tool-manifest.json。

当前生成的功能面：230 种 App Intent 操作类型、85 种 Interactive Snippet 视图、 15 个 AppEnum 选择器，以及一个仅限 iOS 的提供程序，其中包含 8 个与预览运行时相匹配的只读 App Shortcuts。无会话发现卡片使用 MCP 架构版本 2025-11-25。

安全模型

AirMCP 将本地应用访问视为受治理的操作层，而非供 Agent 盲目使用的 Shell。

这一说法可供验证，并非营销辞令：读取第一方 airmcp://trust 资源，即可获得实时的 governed 判定；该判定由防篡改审计链、当前 HITL 级别、速率限制／紧急停止状态和审计密钥等级综合生成——在扩大任何工具访问权限之前即可获取。使用 preview_action 预览任何破坏性调用，即可准确查看它将记录的内容以及是否会受到门控，而无需实际执行。

• 默认 sensitive-only HITL 级别下，对破坏性和敏感操作进行逐次调用人工审批。
• HMAC 链式审计日志位于 ~/.airmcp/audit.jsonl，并通过测试覆盖篡改检测。
• 原生 Trust Center用于查看受治理运行的时间线、审批状态、审计完整性、紧急控制、权限探测和已脱敏的本地导出。 后台绝不会读取审计历史：点击 Load 或 Refresh 会明确发起一次 audit_log 请求，生效的 HITL 策略可能要求对此调用进行审批。
• 速率限制：全局每分钟 60 次，破坏性操作每小时 10 次。
• 紧急停止：touch ~/.config/airmcp/emergency-stop 可在不重启服务的情况下阻止破坏性工具。
• 入站 HTTP 策略通过 AIRMCP_ALLOW_NETWORK 配置：默认仅允许回环访问；如需扩大开放范围，可使用令牌、来源或 OAuth 模式。
• OAuth 2.1 + Resource Indicators适用于需要范围访问控制的 HTTP 运行时，并支持 RS256/ES256 JWT 验证。

环境变量索引见 docs/environment.md。 HTTP 策略详情见 RFC 0002，OAuth 详情见 RFC 0005。

客户端设置

包含已签名 AirMCP.app ZIP 的版本支持由应用拥有的桌面模式：每个已连接的 客户端背后都有一个本地运行时。每次安装的令牌仅通过明确操作创建：在 AirMCP.app 中选择 Start Local Runtime，或通过选择加入的应用运行时客户端连接， 例如 --connect-clients / connect-clients。令牌存储在：

~/Library/Application Support/AirMCP/http-token

macOS 设置窗口基于用户同意：首次会自动显示，重新打开时会从上次的步骤继续。 仅打开或浏览设置不会启动运行时或修改客户端；首次运行时，如果没有运行时，选择 Finish Later 只会保存所选项。如果应用拥有的运行时已在运行且所选项已更改， Finish Setup 可能会停止并重启确切的已拥有运行时实例，以确保已保存的范围与 实际生效的范围一致。Start Local Runtime 会创建令牌并选择加入自动启动；只有在 各客户端分别执行 Connect 操作并通过新一轮范围／就绪状态检查后，才会注册该客户端。

可以检查或禁用现有的 Codex 注册，而无需删除其设置：

npx airmcp codex status
npx airmcp codex disable

npx airmcp codex 命令遵循其子 Codex CLI 当前使用的用户配置根目录：首先是 AIRMCP_CODEX_CONFIG_PATH，其次是 $CODEX_HOME/config.toml，最后是 ~/.codex/config.toml。显式指定的覆盖路径会相对于调用时的工作目录解析，且文件名 必须为 config.toml。

Stdio 客户端可以代理到应用拥有的 HTTP 运行时：

npx -y airmcp connect --url http://127.0.0.1:3847/mcp

使用该代理时，将 AIRMCP_HTTP_TOKEN 设为令牌值。

示例：

claude mcp add --env AIRMCP_HTTP_TOKEN=<token> airmcp -- npx -y airmcp connect --url http://127.0.0.1:3847/mcp
codex mcp add --env AIRMCP_HTTP_TOKEN=<token> airmcp -- npx -y airmcp connect --url http://127.0.0.1:3847/mcp

开发或使用隔离的客户端自有运行时时，仍可使用直接 Stdio 模式：

npx -y airmcp

基于浏览器的 MCP 客户端应使用带令牌和来源检查的 HTTP 模式。浏览器／OAuth 路径请参见 docs/oauth-browser-pkce.md。

App Intents 和快捷指令

AirMCP 根据同一份 MCP 工具清单生成 App Intent 操作。在 macOS 上， 这些操作可在快捷指令操作库中使用；Apple 不支持 macOS 上的 AppShortcutsProvider 短语界面。iOS 预览版还可以编译以工作流为先的 App Shortcuts 提供程序。

破坏性意图的源代码生成需在构建／代码生成时通过 AIRMCP_APPINTENTS_DESTRUCTIVE=true 选择启用；在已构建的应用旁设置该变量 不会扩展该二进制文件的意图范围。 AskAirMCPIntent 和基于 FoundationModels 的 Apple Intelligence 路径仅供预览， 且需要显式 Swift 构建。

指南：docs/shortcuts.md。架构： RFC 0007。

本地开发

git clone https://github.com/heznpc/AirMCP.git
cd AirMCP
npm install
npm run build
node dist/index.js

常用检查：

npm test
npm run mcp:validate
npm run dev:test -- notes
npm run dev:test:changed

Swift 桥接：

npm run swift-build

FoundationModels 预览版构建需要 macOS 26 或更高版本、Apple Silicon、兼容的 SDK，以及显式编译标志：

cd swift
swift build -c release -Xswiftc -DAIRMCP_ENABLE_FOUNDATION_MODELS

Swift 或应用构建后，本地构建产物可能会增多。若要检查或清理 被忽略的构建产物：

npm run clean:local
npm run clean:local:apply
npm run size:check

测试指南：docs/testing.md。

要求

• 服务器运行时需要 macOS。
• Node.js 20 或更高版本。
• 根据启用的模块需要授予 macOS 自动化、辅助功能、完全磁盘访问、位置、蓝牙或 照片权限。
• 自包含的 AirMCP.app 发行包内置固定版本的 Node 运行时和常规 Swift 桥接程序。npm 包和 .mcpb 不内置 Swift 二进制文件；使用这些产物的用户若要使用 Swift 支持的工具，需从源代码构建该二进制文件，或安装内置该文件的已签名 AirMCP.app 发行包。
• 基于 FoundationModels 的 Apple Intelligence 预览功能需要 macOS 26 或更高版本、 Apple Silicon，以及 AIRMCP_ENABLE_FOUNDATION_MODELS。

macOS 运行时是当前受支持的版本。iOS 运行时处于预览阶段；visionOS 和 watchOS 仍在路线图中，尚未发布。

文档

• 工具清单：已注册工具的生成列表。
• 工作流：目标工作流和提示词目录。
• Skills DSL：YAML 工作流语法和内置功能。
• 快捷指令：macOS App Intent 操作和仅限 iOS 的 App Shortcuts 界面。
• 环境变量：所有运行时配置项。
• MCPB 安装：Claude Desktop 扩展包。
• OAuth 浏览器 PKCE：浏览器客户端设置。
• RFC 索引：设计记录和架构说明。
• 测试：开发测试工作流。
• 项目方向：产品方向和定位。

贡献

请参阅 CONTRIBUTING.md，了解开发环境设置、代码风格和 PR 指南。

首次贡献者可以查看 good first issue。

社区

• GitHub 讨论区
• 问题
• 更新日志

许可证

MIT