Your AI assistant can use the Mac apps you already use. Ask for something in
plain language and AirMCP does it in the real Notes, Mail, Calendar, Reminders,
Messages, Photos, Safari, Finder, and Shortcuts on your machine — your actual
data, not a copy and not a sandbox. The macOS runtime is available today; the
iOS runtime is in preview.
Governed MCP runtime for the Apple ecosystem — verified control over Notes, Mail, Calendar, Shortcuts, and more.
星數
17
工具
—
可用率
—
Release status (2026-10-27 KST): v2.16.7 is available through npm and
the MCPB extension. Its macOS app ZIP is still unavailable because Apple
notarization authentication failed. Use the CLI or
MCPB path; see the release verification record
for completed checks and the remaining app-distribution gate.
"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."
Start on macOS with Node.js 20+:
npx airmcp init
Then ask your client. Works with Claude, Codex, Cursor, Raycast, Xcode agents,
and any other MCP client. Nothing reads or changes a client's settings until you
opt in.
AirMCP is the connector and control layer, not another agent. Destructive calls
preview before they run, approval is per-call, and the audit chain is
tamper-evident and verifiable by you — read airmcp://trust and check it
yourself. Details in Safety Model.
Apple workspace tools for Notes, Reminders, Calendar, Contacts, Mail,
Messages, Music, Finder, Safari, Photos, Shortcuts, system control, screen
capture, Weather, Maps, Location, Bluetooth, and more.
Google Workspace tools for Gmail, Drive, Sheets, Calendar, Docs, Tasks,
People, and raw gws CLI access.
Profiles and progressive exposure so clients start with a small front
door instead of every loaded tool.
Skills DSL workflows with parallel, loop, retry, on_error, runtime
inputs, and event triggers.
App Intent action bridge generated from the MCP manifest for macOS
Shortcuts, with an iOS-only App Shortcuts provider and destructive intents gated separately.
Native Swift bridge for EventKit, PhotoKit, HealthKit, Vision, on-device
semantic search, and FoundationModels preview builds. AirMCP.app embeds the
normal bridge; it is optional for npm and MCPB users, who can build it
separately when needed.
Dual transport: stdio for standard MCP clients, HTTP/SSE for shared
local runtimes, browser clients, registries, and always-on hosts.
Apple Platform Direction
AirMCP is one governed action layer with platform-specific roles, rather than a
copy of the full Mac runtime on every device.
Platform
Status
Role
macOS
Available
Full local MCP runtime and broad Apple app and system integration.
iOS / iPadOS
Preview
Native Calendar, Reminders, Contacts, Health, and Location actions, plus in-process AppIntents.
visionOS
Roadmap
Spatial interaction and native actions, with Mac routing for Mac-only automation.
watchOS
Roadmap
Commands, notifications, and per-call approval through a paired iPhone runtime.
The shared Swift and AppIntents layers are the portability boundary. Platform
sandboxing and lifecycle rules still determine which actions run locally and
which route to a paired Mac or iPhone.
The desktop distribution is a Developer-ID-signed, notarized, and stapled
AirMCP-<version>.zip. Check the selected version's assets in
Releases before choosing this path:
v2.16.6 and v2.16.7 have no app ZIP. The v2.16.7 attempt stopped at Apple
notarization account authentication; its app distribution is incomplete. The ZIP
needs no build step: the embedded Node runtime, the Swift
bridge, the menubar Trust Center, and the generated App Intents (Shortcuts
actions) and widget are all included.
Choose v2.16.5 or later with an app ZIP attached. The v2.16.3 and v2.16.4 releases carry an app ZIP
that signs, notarizes, and staples correctly but crashes on launch before the
menubar icon appears — a resource-bundle path bug fixed in v2.16.5.
Download AirMCP-<version>.zip and unzip it.
Move AirMCP.app to /Applications and open it. Gatekeeper accepts it
offline because the notarization ticket is stapled.
Follow the consent-driven Setup window; nothing starts and no client is
edited until you choose it.
CLI wizard
Install Node.js 20+, then run:
npx airmcp init
The wizard selects a profile and stores preferences in
~/.config/airmcp/config.json. Client registration is a separate consent
step whose default is No; no Claude, Codex, Cursor, or Windsurf setting is
read or changed until you opt in.
For Codex, Claude Code, Cursor, Windsurf, and other stdio clients, use the
direct runtime, or the app-owned runtime after installing the signed
AirMCP-<version>.zip from a release that includes that asset:
npx airmcp init --no-clients
npx airmcp connect-clients --client-runtime direct --dry-run
npx airmcp connect-clients --client-runtime direct
The app-owned runtime is available only after installing that signed app ZIP
and explicitly choosing Start Local Runtime. Releases before v2.16.5 have
no app asset, or one that cannot launch; do not configure a client to wait for
AirMCP.app on those.
AirMCP is designed to keep a large local capability surface usable without
dumping the full catalog into every client context.
The complete generated catalog currently contains 293 tools across 32 modules.
Profiles and progressive exposure keep clients from loading it all at once.
Profiles: starter, communications-safe, productivity, full, or
custom.
Tool exposure: progressive, profile, or full.
Module packs: enable only the packs you want with npx airmcp modules or
AIRMCP_MODULE_PACKS=core,productivity.
Task sessions: start_tool_session, discover_tools, and run_tool
allow a broad runtime to behave like a narrow task-specific toolbelt.
Opt-in network modules: webhooks and powerautomate stay off in every
profile until explicitly enabled.
today-overview is the starter-safe first workflow: it reads only Calendar
and Reminders and never writes data. Paste the printed prompt into a connected
MCP client for a governed first run with client authorization and AirMCP audit
coverage.
workflows <id> --preview is a separate local diagnostic. It reads Apple apps
directly, bypasses the MCP governance path, and creates no AirMCP audit entry;
do not use it as the first-success workflow. Broader diagnostics such as
daily-briefing --preview report missing modules before reading live data.
Current generated surfaces: 230 App Intent action types, 85 Interactive Snippet views,
15 AppEnum pickers, and an iOS-only provider with 8 read-only App Shortcuts that match the preview runtime. The sessionless discovery card uses MCP schema version
2025-11-25.
Safety Model
AirMCP treats local app access as a governed action layer, not a blind shell for
agents.
The claim is verifiable, not marketing: read the first-party airmcp://trust
resource for a live governed verdict composed from the tamper-evident audit
chain, the active HITL level, the rate-limit / emergency-stop state, and the
audit key grade — available before any tool access is widened. Preview any
destructive call with preview_action to see exactly what it would record and
whether it would be gated, without running it.
Per-call human approval for destructive and sensitive actions at the
default sensitive-only HITL level.
HMAC-chained audit log at ~/.airmcp/audit.jsonl, with tamper detection
covered by tests.
Native Trust Center for governed-run timelines, approval state, audit
integrity, emergency controls, permission probes, and redacted local export.
Audit history is never read in the background: Load or Refresh makes
one explicit audit_log request, and the effective HITL policy may require
approval for that call.
Rate limits: 60/min globally and 10 destructive/hr.
Emergency stop: touch ~/.config/airmcp/emergency-stop blocks destructive
tools without restarting the server.
Inbound HTTP policy through AIRMCP_ALLOW_NETWORK: loopback-only by
default, with token, origin, or OAuth modes available for wider exposure.
OAuth 2.1 + Resource Indicators for HTTP runtimes that need scoped access
control, with RS256/ES256 JWT verification.
Releases that include the signed AirMCP.app ZIP support an app-owned
desktop pattern with one local runtime behind every connected
client. A per-install token is created only by an explicit action: Start
Local Runtime in AirMCP.app, or an opted-in app-runtime client connection
such as --connect-clients / connect-clients. It is stored at:
~/Library/Application Support/AirMCP/http-token
The macOS Setup window is consent-driven: it appears automatically once and
resumes its last step when reopened. Merely opening or moving through Setup
does not start the runtime or edit a client, and first-run Finish Later
with no runtime saves the selection only. If an app-owned runtime is already
running and the selection changed, Finish Setup may stop and restart that
exact owned generation so the persisted and effective scopes match. Start
Local Runtime creates the token and opts into automatic startup; each client
is registered only after its own Connect action and a fresh
scope/readiness check.
Existing Codex registrations can be inspected or disabled without deleting
their settings:
npx airmcp codex status
npx airmcp codex disable
The npx airmcp codex commands follow their child Codex CLI's active user
config root: AIRMCP_CODEX_CONFIG_PATH first, then
$CODEX_HOME/config.toml, then ~/.codex/config.toml. The explicit override
is resolved against the invoking working directory and must be named
config.toml.
Stdio clients can proxy into the app-owned HTTP runtime:
Direct stdio mode still works for development or isolated client-owned runtimes:
npx -y airmcp
Browser-based MCP clients should use HTTP mode with token and origin checks. See
docs/oauth-browser-pkce.md for the browser/OAuth
path.
App Intents and Shortcuts
AirMCP generates App Intent actions from the same MCP tool manifest. On macOS,
those actions are available in the Shortcuts action library; Apple does not
support the AppShortcutsProvider phrase surface on macOS. iOS preview builds
can additionally compile the workflow-first App Shortcuts provider.
Destructive intent source generation is opt-in at build/codegen time with
AIRMCP_APPINTENTS_DESTRUCTIVE=true; setting it beside an already-built app
does not expand that binary's intent surface.
AskAirMCPIntent and FoundationModels-backed Apple Intelligence paths are
preview-only and require explicit Swift builds.
macOS Automation, Accessibility, Full Disk Access, Location, Bluetooth, or
Photos permissions as required by the modules you enable.
The self-contained AirMCP.app distribution embeds its fixed Node runtime and
the normal Swift bridge. The npm package and .mcpb do not embed the Swift
binary; users of those artifacts build it from source for Swift-backed tools, or
install the signed AirMCP.app release asset, which embeds it.
FoundationModels-backed Apple Intelligence preview requires macOS 26+, Apple
Silicon, and AIRMCP_ENABLE_FOUNDATION_MODELS.
The macOS runtime is the current supported release. The iOS runtime is a
preview; visionOS and watchOS are roadmap targets, not released products.