\n\n# AirMCP\n\n[](https://www.npmjs.com/package/airmcp)\n[](https://github.com/heznpc/AirMCP/actions/workflows/ci.yml)\n[](LICENSE)\n[](https://github.com/heznpc/AirMCP/stargazers)\n\n**Your AI assistant can use the Mac apps you already use.** Ask for something in\nplain language and AirMCP does it in the real Notes, Mail, Calendar, Reminders,\nMessages, Photos, Safari, Finder, and Shortcuts on your machine — your actual\ndata, not a copy and not a sandbox. The macOS runtime is available today; the\niOS runtime is in preview.\n\n```text\n\"Brief me on today's calendar, overdue reminders, and unread mail.\"\n\"For my next meeting, pull up the related notes, contacts, files, and reminders.\"\n\"Search my Safari tabs for that article and save a summary to Notes.\"\n\"Draft replies to the urgent mail, but ask me before sending anything.\"\n\"Run my Morning Routine shortcut.\"\n```\n\nStart on macOS with Node.js 20+:\n\n```bash\nnpx airmcp init\n```\n\nThen ask your client. Works with Claude, Codex, Cursor, Raycast, Xcode agents,\nand any other MCP client. Nothing reads or changes a client's settings until you\nopt in.\n\nMore to try: [Common Workflows](#common-workflows) ·\n[every tool](llms-full.txt) · [Quick Start](#quick-start)\n\n### It does not act behind your back\n\nAirMCP is the connector and control layer, not another agent. Destructive calls\npreview before they run, approval is per-call, and the audit chain is\ntamper-evident and verifiable by you — read `airmcp://trust` and check it\nyourself. Details in [Safety Model](#safety-model).\n\n
\n \n
\n\n
Generated from a real local MCP round-trip by scripts/demo/governed-flow.mjs — real terminal output, not a staged transcript.
\n\n> Multi-language project page: [heznpc.github.io/AirMCP](https://heznpc.github.io/AirMCP/)\n\n## What You Get\n\n- **Apple workspace tools** for Notes, Reminders, Calendar, Contacts, Mail,\n Messages, Music, Finder, Safari, Photos, Shortcuts, system control, screen\n capture, Weather, Maps, Location, Bluetooth, and more.\n- **Google Workspace tools** for Gmail, Drive, Sheets, Calendar, Docs, Tasks,\n People, and raw `gws` CLI access.\n- **Profiles and progressive exposure** so clients start with a small front\n door instead of every loaded tool.\n- **Skills DSL workflows** with `parallel`, `loop`, `retry`, `on_error`, runtime\n inputs, and event triggers.\n- **App Intent action bridge** generated from the MCP manifest for macOS\n Shortcuts, with an iOS-only App Shortcuts provider and destructive intents gated separately.\n- **Native Swift bridge** for EventKit, PhotoKit, HealthKit, Vision, on-device\n semantic search, and FoundationModels preview builds. AirMCP.app embeds the\n normal bridge; it is optional for npm and MCPB users, who can build it\n separately when needed.\n- **Dual transport**: stdio for standard MCP clients, HTTP/SSE for shared\n local runtimes, browser clients, registries, and always-on hosts.\n\n## Apple Platform Direction\n\nAirMCP is one governed action layer with platform-specific roles, rather than a\ncopy of the full Mac runtime on every device.\n\n| Platform | Status | Role |\n| --- | --- | --- |\n| macOS | Available | Full local MCP runtime and broad Apple app and system integration. |\n| iOS / iPadOS | Preview | Native Calendar, Reminders, Contacts, Health, and Location actions, plus in-process AppIntents. |\n| visionOS | Roadmap | Spatial interaction and native actions, with Mac routing for Mac-only automation. |\n| watchOS | Roadmap | Commands, notifications, and per-call approval through a paired iPhone runtime. |\n\nThe shared Swift and AppIntents layers are the portability boundary. Platform\nsandboxing and lifecycle rules still determine which actions run locally and\nwhich route to a paired Mac or iPhone.\n\n## Quick Start\n\n### Claude Desktop one-click\n\n1. Download `airmcp-.mcpb` from\n [Releases](https://github.com/heznpc/AirMCP/releases).\n2. Drag it onto Claude Desktop, or use **Settings -> Extensions -> Install from\n file...**.\n3. Choose modules in the install form and finish setup.\n\nFull guide: [docs/mcpb.md](docs/mcpb.md).\n\n### macOS app (signed + notarized)\n\nEvery release from v2.16.5 on ships a Developer-ID-signed, notarized, and\nstapled `AirMCP-.zip` in\n[Releases](https://github.com/heznpc/AirMCP/releases). It is the one artifact\nwith the full surface and no build step: the embedded Node runtime, the Swift\nbridge, the menubar Trust Center, and the generated App Intents (Shortcuts\nactions) and widget are all included.\n\nInstall v2.16.5 or later. The v2.16.3 and v2.16.4 releases carry an app ZIP\nthat signs, notarizes, and staples correctly but crashes on launch before the\nmenubar icon appears — a resource-bundle path bug fixed in v2.16.5.\n\n1. Download `AirMCP-.zip` and unzip it.\n2. Move `AirMCP.app` to `/Applications` and open it. Gatekeeper accepts it\n offline because the notarization ticket is stapled.\n3. Follow the consent-driven Setup window; nothing starts and no client is\n edited until you choose it.\n\n### CLI wizard\n\nInstall Node.js 20+, then run:\n\n```bash\nnpx airmcp init\n```\n\nThe wizard selects a profile and stores preferences in\n`~/.config/airmcp/config.json`. Client registration is a separate consent\nstep whose default is **No**; no Claude, Codex, Cursor, or Windsurf setting is\nread or changed until you opt in.\n\nFor Codex, Claude Code, Cursor, Windsurf, and other stdio clients, use the\ndirect runtime, or the app-owned runtime after installing the signed\n`AirMCP-.zip` that ships with each release since v2.16.5:\n\n```bash\nnpx airmcp init --no-clients\nnpx airmcp connect-clients --client-runtime direct --dry-run\nnpx airmcp connect-clients --client-runtime direct\n```\n\nThe app-owned runtime is available only after installing that signed app ZIP\nand explicitly choosing **Start Local Runtime**. Releases before v2.16.5 have\nno app asset, or one that cannot launch; do not configure a client to wait for\nAirMCP.app on those.\n\nNon-interactive examples:\n\n```bash\nnpx airmcp init --profile starter --yes\nnpx airmcp init --profile communications-safe --yes\nnpx airmcp init --profile productivity --yes\nnpx airmcp init --profile productivity --yes --connect-clients\nnpx airmcp init --profile productivity --yes --connect-clients --client-runtime direct\n```\n\nCheck the install:\n\n```bash\nnpx airmcp doctor\n```\n\n## Common Workflows\n\nOnce connected, ask your MCP client in natural language:\n\n- \"Tell me today's calendar events and overdue reminders. Do not change\n anything.\"\n- \"Brief me on today's calendar, overdue reminders, unread mail, and recent\n notes.\"\n- \"Turn today's meetings into a prep checklist.\"\n- \"Draft replies for urgent mail, but ask before sending anything.\"\n- \"For my next meeting, find related notes, contacts, files, and reminders.\"\n- \"Search my Safari tabs for that article and save the summary to Notes.\"\n- \"Run my Morning Routine shortcut.\"\n- \"Take a screenshot and save it to my Desktop.\"\n\nMore workflow examples live in [docs/workflows.md](docs/workflows.md).\n\n## Runtime Model\n\nAirMCP is designed to keep a large local capability surface usable without\ndumping the full catalog into every client context.\n\nThe complete generated catalog currently contains 298 tools across 32 modules.\nProfiles and progressive exposure keep clients from loading it all at once.\n\n- **Profiles**: `starter`, `communications-safe`, `productivity`, `full`, or\n `custom`.\n- **Tool exposure**: `progressive`, `profile`, or `full`.\n- **Module packs**: enable only the packs you want with `npx airmcp modules` or\n `AIRMCP_MODULE_PACKS=core,productivity`.\n- **Task sessions**: `start_tool_session`, `discover_tools`, and `run_tool`\n allow a broad runtime to behave like a narrow task-specific toolbelt.\n- **Opt-in network modules**: `webhooks` and `powerautomate` stay off in every\n profile until explicitly enabled.\n\nUseful commands:\n\n```bash\nnpx airmcp modules\nnpx airmcp modules enable productivity --install\nnpx airmcp --full\nnpx airmcp workflows\nnpx airmcp workflows --readiness\nnpx airmcp workflows today-overview --prompt\n```\n\n`today-overview` is the starter-safe first workflow: it reads only Calendar\nand Reminders and never writes data. Paste the printed prompt into a connected\nMCP client for a governed first run with client authorization and AirMCP audit\ncoverage.\n\n`workflows --preview` is a separate local diagnostic. It reads Apple apps\ndirectly, bypasses the MCP governance path, and creates no AirMCP audit entry;\ndo not use it as the first-success workflow. Broader diagnostics such as\n`daily-briefing --preview` report missing modules before reading live data.\n\nThe complete generated tool manifest is in\n[docs/tool-manifest.json](docs/tool-manifest.json).\n\nCurrent generated surfaces: 234 App Intent action types, 86 Interactive Snippet views,\n15 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\n2025-11-25.\n\n## Safety Model\n\nAirMCP treats local app access as a governed action layer, not a blind shell for\nagents.\n\nThe claim is verifiable, not marketing: read the first-party `airmcp://trust`\nresource for a live `governed` verdict composed from the tamper-evident audit\nchain, the active HITL level, the rate-limit / emergency-stop state, and the\naudit key grade — available before any tool access is widened. Preview any\ndestructive call with `preview_action` to see exactly what it would record and\nwhether it would be gated, without running it.\n\n- **Per-call human approval** for destructive and sensitive actions at the\n default `sensitive-only` HITL level.\n- **HMAC-chained audit log** at `~/.airmcp/audit.jsonl`, with tamper detection\n covered by tests.\n- **Native Trust Center** for governed-run timelines, approval state, audit\n integrity, emergency controls, permission probes, and redacted local export.\n Audit history is never read in the background: **Load** or **Refresh** makes\n one explicit `audit_log` request, and the effective HITL policy may require\n approval for that call.\n- **Rate limits**: 60/min globally and 10 destructive/hr.\n- **Emergency stop**: `touch ~/.config/airmcp/emergency-stop` blocks destructive\n tools without restarting the server.\n- **Inbound HTTP policy** through `AIRMCP_ALLOW_NETWORK`: loopback-only by\n default, with token, origin, or OAuth modes available for wider exposure.\n- **OAuth 2.1 + Resource Indicators** for HTTP runtimes that need scoped access\n control, with RS256/ES256 JWT verification.\n\nEnvironment variables are indexed in [docs/environment.md](docs/environment.md).\nHTTP policy details are in\n[RFC 0002](docs/rfc/0002-http-allow-network.md), and OAuth details are in\n[RFC 0005](docs/rfc/0005-oauth-resource-indicators.md).\n\n## Client Setup\n\nEach release since v2.16.5 includes a runnable signed AirMCP.app ZIP; the\napp-owned desktop pattern keeps one local runtime behind every connected\nclient. A per-install token is created only by an explicit action: **Start\nLocal Runtime** in AirMCP.app, or an opted-in app-runtime client connection\nsuch as `--connect-clients` / `connect-clients`. It is stored at:\n\n```text\n~/Library/Application Support/AirMCP/http-token\n```\n\nThe macOS Setup window is consent-driven: it appears automatically once and\nresumes its last step when reopened. Merely opening or moving through Setup\ndoes not start the runtime or edit a client, and first-run **Finish Later**\nwith no runtime saves the selection only. If an app-owned runtime is already\nrunning and the selection changed, **Finish Setup** may stop and restart that\nexact owned generation so the persisted and effective scopes match. **Start\nLocal Runtime** creates the token and opts into automatic startup; each client\nis registered only after its own **Connect** action and a fresh\nscope/readiness check.\n\nExisting Codex registrations can be inspected or disabled without deleting\ntheir settings:\n\n```bash\nnpx airmcp codex status\nnpx airmcp codex disable\n```\n\nThe `npx airmcp codex` commands follow their child Codex CLI's active user\nconfig root: `AIRMCP_CODEX_CONFIG_PATH` first, then\n`$CODEX_HOME/config.toml`, then `~/.codex/config.toml`. The explicit override\nis resolved against the invoking working directory and must be named\n`config.toml`.\n\nStdio clients can proxy into the app-owned HTTP runtime:\n\n```bash\nnpx -y airmcp connect --url http://127.0.0.1:3847/mcp\n```\n\nSet `AIRMCP_HTTP_TOKEN` to the token value when using that proxy.\n\nExamples:\n\n```bash\nclaude mcp add --env AIRMCP_HTTP_TOKEN= airmcp -- npx -y airmcp connect --url http://127.0.0.1:3847/mcp\ncodex mcp add --env AIRMCP_HTTP_TOKEN= airmcp -- npx -y airmcp connect --url http://127.0.0.1:3847/mcp\n```\n\nDirect stdio mode still works for development or isolated client-owned runtimes:\n\n```bash\nnpx -y airmcp\n```\n\nBrowser-based MCP clients should use HTTP mode with token and origin checks. See\n[docs/oauth-browser-pkce.md](docs/oauth-browser-pkce.md) for the browser/OAuth\npath.\n\n## App Intents and Shortcuts\n\nAirMCP generates App Intent actions from the same MCP tool manifest. On macOS,\nthose actions are available in the Shortcuts action library; Apple does not\nsupport the `AppShortcutsProvider` phrase surface on macOS. iOS preview builds\ncan additionally compile the workflow-first App Shortcuts provider.\n\nDestructive intent source generation is opt-in at build/codegen time with\n`AIRMCP_APPINTENTS_DESTRUCTIVE=true`; setting it beside an already-built app\ndoes not expand that binary's intent surface.\n`AskAirMCPIntent` and FoundationModels-backed Apple Intelligence paths are\npreview-only and require explicit Swift builds.\n\nGuide: [docs/shortcuts.md](docs/shortcuts.md). Architecture:\n[RFC 0007](docs/rfc/0007-app-intent-bridge.md).\n\n## Local Development\n\n```bash\ngit clone https://github.com/heznpc/AirMCP.git\ncd AirMCP\nnpm install\nnpm run build\nnode dist/index.js\n```\n\nUseful checks:\n\n```bash\nnpm test\nnpm run mcp:validate\nnpm run dev:test -- notes\nnpm run dev:test:changed\n```\n\nSwift bridge:\n\n```bash\nnpm run swift-build\n```\n\nFoundationModels preview builds require macOS 26+, Apple Silicon, a compatible\nSDK, and the explicit compile flag:\n\n```bash\ncd swift\nswift build -c release -Xswiftc -DAIRMCP_ENABLE_FOUNDATION_MODELS\n```\n\nLocal build artifacts can grow after Swift or app builds. To inspect or reclaim\nignored artifacts:\n\n```bash\nnpm run clean:local\nnpm run clean:local:apply\nnpm run size:check\n```\n\nTesting guide: [docs/testing.md](docs/testing.md).\n\n## Requirements\n\n- macOS for the server runtime.\n- Node.js 20 or newer.\n- macOS Automation, Accessibility, Full Disk Access, Location, Bluetooth, or\n Photos permissions as required by the modules you enable.\n- The self-contained AirMCP.app distribution embeds its fixed Node runtime and\n the normal Swift bridge. The npm package and `.mcpb` do not embed the Swift\n binary; users of those artifacts build it from source for Swift-backed tools, or\n install the signed AirMCP.app release asset, which embeds it.\n- FoundationModels-backed Apple Intelligence preview requires macOS 26+, Apple\n Silicon, and `AIRMCP_ENABLE_FOUNDATION_MODELS`.\n\nThe macOS runtime is the current supported release. The iOS runtime is a\npreview; visionOS and watchOS are roadmap targets, not released products.\n\n## Documentation\n\n- [Tool manifest](docs/tool-manifest.json): generated list of registered tools.\n- [Workflows](docs/workflows.md): target workflows and prompt catalog.\n- [Skills DSL](docs/skills.md): YAML workflow syntax and built-ins.\n- [Shortcuts](docs/shortcuts.md): macOS App Intent actions and the iOS-only App Shortcuts surface.\n- [Environment variables](docs/environment.md): all runtime knobs.\n- [MCPB install](docs/mcpb.md): Claude Desktop extension package.\n- [OAuth browser PKCE](docs/oauth-browser-pkce.md): browser client setup.\n- [RFC index](docs/rfc/README.md): design records and architecture notes.\n- [Testing](docs/testing.md): development test workflow.\n- [Project direction](docs/direction.md): product direction and positioning.\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, code style, and PR\nguidelines.\n\nFirst-time contributors can look for\n[`good first issue`](https://github.com/heznpc/AirMCP/labels/good%20first%20issue).\n\n## Community\n\n- [GitHub Discussions](https://github.com/heznpc/AirMCP/discussions)\n- [Issues](https://github.com/heznpc/AirMCP/issues)\n- [Changelog](CHANGELOG.md)\n\n## License\n\nMIT\n",
"bytes": 16998,
"sha": "f16264b5883ab8074c6d6d6294672c02f6401cf6d560b444d605a095482bdca1",
"repo_slug": "heznpc/airmcp",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_heznpc_airmcp_6733de5d/readme"
}
![\"AirMCP\"](\"icons/airmcp-icon-256.png\"){kind=icon}
\n![\"A](\"docs/demo.gif\")
\n