Airmcp

AirMCP

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.

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.

More to try: Common Workflows · every tool · Quick Start

It does not act behind your back

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.

Generated from a real local MCP round-trip by scripts/demo/governed-flow.mjs — real terminal output, not a staged transcript.

Multi-language project page: heznpc.github.io/AirMCP

What You Get

• 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.

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.

Quick Start

Claude Desktop one-click

1. Download airmcp-<version>.mcpb from Releases.
2. Drag it onto Claude Desktop, or use Settings -> Extensions -> Install from file....
3. Choose modules in the install form and finish setup.

Full guide: docs/mcpb.md.

macOS app (signed + notarized)

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.

1. Download AirMCP-<version>.zip and unzip it.
2. Move AirMCP.app to /Applications and open it. Gatekeeper accepts it offline because the notarization ticket is stapled.
3. 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.

Non-interactive examples:

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

Check the install:

npx airmcp doctor

Common Workflows

Once connected, ask your MCP client in natural language:

• "Tell me today's calendar events and overdue reminders. Do not change anything."
• "Brief me on today's calendar, overdue reminders, unread mail, and recent notes."
• "Turn today's meetings into a prep checklist."
• "Draft replies for urgent mail, but ask before sending anything."
• "For my next meeting, find related notes, contacts, files, and reminders."
• "Search my Safari tabs for that article and save the summary to Notes."
• "Run my Morning Routine shortcut."
• "Take a screenshot and save it to my Desktop."

More workflow examples live in docs/workflows.md.

Runtime Model

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.

Useful commands:

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 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.

The complete generated tool manifest is in docs/tool-manifest.json.