AirMCP

AirMCP

Apple-native action runtime for MCP clients. AirMCP lets Claude, Codex, Cursor, Raycast, Siri, Shortcuts, Xcode agents, and other MCP-capable AI clients read, organize, and act across your Mac apps through one governed local runtime.

The catalog is broad: 296 tools across 32 modules. The important part is the layer underneath: profile-based exposure, task-scoped tool sessions, per-call human approval, HMAC-chained audit logs, rate limits, OAuth scopes, and local controls for sensitive Apple workspace actions.

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.
• Siri and Shortcuts bridge generated from the MCP manifest through AppIntents, with destructive intents gated separately.
• Native Swift bridge, optional for EventKit, PhotoKit, HealthKit, Vision, on-device semantic search, and FoundationModels preview builds.
• Dual transport: stdio for standard MCP clients, HTTP/SSE for shared local runtimes, browser clients, registries, and always-on hosts.

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.

CLI wizard

Install Node.js 20+, then run:

npx airmcp init

The wizard selects a profile, writes MCP client config, and stores preferences in ~/.config/airmcp/config.json.

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 --client-runtime direct

Check the install:

npx airmcp doctor

Common Workflows

Once connected, ask your MCP client in natural language:

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

• 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 daily-briefing --prompt

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

Current generated surfaces: 233 Shortcuts / Siri AppIntents, 84 Interactive Snippet views, and 13 AppEnum pickers. 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.