AirMCP

Safe action layer for your Apple workspace. AirMCP lets Siri, Shortcuts, Claude, Codex, Cursor, Raycast, opencode, Gemini CLI, Xcode agents, and any MCP-capable AI read, organize, and act across your Mac apps with approval gates for sensitive actions, HMAC-chained audit logs, rate limits, OAuth scopes, and local-first controls. The broad Apple + Google Workspace tool catalog is the surface; the workflow engine, semantic memory, Swift bridges, and governance layer are the runtime underneath.

Part of: Human-Controlled AI Systems · Research Program 1 (anchor — Apple-side agent governance).

Requires: macOS for the server. The recommended desktop path is the AirMCP menubar app: it owns the loopback HTTP runtime, while Claude/Codex/Cursor attach to it as clients. The direct CLI server (npx -y airmcp) still works for development and boots the starter profile with progressive tools/list exposure: a small front door (profile_status, list_profiles, list_module_packs, discover_tools, describe_tool, run_tool, and core starter tools) instead of every loaded tool. Use AIRMCP_PROFILE=communications-safe|productivity|full|custom to choose a module profile, AIRMCP_TOOL_EXPOSURE=profile|full to widen tools/list, npx airmcp modules enable productivity or AIRMCP_MODULE_PACKS=core,productivity to activate only selected DLC-like packs, or --full / AIRMCP_FULL=true to request all 29 standard modules / 295 tools when the matching add-ons are installed (the 2 opt-in network modules — webhooks, powerautomate — stay off unless explicitly enabled). New app/CLI-created configs require task sessions for hidden run_tool dispatch; no-config direct stdio keeps the compatible path unless AIRMCP_REQUIRE_TOOL_SESSION=true is set. Most tools are pure JXA and work on macOS 14+ with no extra setup. Swift-backed tools — HealthKit, on-device semantic search, recurring events/reminders, photo import/delete/classify, Vision, Speech, Location, Bluetooth, and Apple Intelligence previews — need the optional Swift bridge — build it from a source checkout with npm run swift-build (it ships in none of the distribution channels — the npm tarball, the .mcpb bundle, or the menubar .app — so build it from source as above); without it those tools return a clear "Swift bridge not found" error and everything else keeps working. FoundationModels-backed Apple Intelligence and AskAirMCPIntent additionally require macOS 26+ on Apple Silicon and an opt-in Swift build with AIRMCP_ENABLE_FOUNDATION_MODELS.

Available in multiple languages at the project landing page.

What this is — at a glance

• Currently implemented — 295 tools across 31 modules (2 opt-in: webhooks, powerautomate) behind first-class profiles (starter, communications-safe, productivity, full) and progressive exposure (discover_tools + run_tool keep hidden tools callable without dumping the full catalog into every client context); HMAC-chained audit log with tamper-detection test suite; default HITL approval per destructive/sensitive call; rate limit (60/min + 10 destructive/hr); allowNetwork inbound HTTP exposure policy (RFC 0002); OAuth 2.1 + Resource Indicators (RFC 0005 Steps 1+2 — RS256/ES256 JWT, scope gate, .well-known/oauth-protected-resource per RFC 9728); sessionless .well-known/mcp.json discovery; 232 Shortcuts/AppIntents auto-generated from the full tool manifest; native SwiftUI menubar app (ad-hoc signed; Developer ID notarization pending); Claude Code plugin package (.claude-plugin/plugin.json + .mcp.json at repo root, with the .mcp.json invocation pinned to the same npm version as the manifest so the marketplace SHA-approval and the installed runtime always agree). On every CI run, npm run mcp:validate boots the built dist/index.js under a pinned @modelcontextprotocol/inspector --cli and checks the tools/list response for JSON-RPC envelope drift, embedded error envelopes, and zero-tool responses — this is a wire-shape gate, not a substitute for the HMAC / HITL / audit primitives, which have their own tests.
• Planned — RFC 0005 Step 3 browser PKCE guide; stateless streamable HTTP for horizontal scale per MCP 2026 roadmap; iOS/visionOS exploration (v3.0+); consolidated registry re-publishing across Anthropic MCP Registry, Smithery, PulseMCP, Glama, MCP Market, Cline Marketplace, LobeHub (the .well-known/mcp.json endpoint is published, mcpName is set, and past ad-hoc registrations exist on some registries but their versions/metadata have drifted out of date — a single self-publishing PR will re-push the current manifest to each); Claude Code Plugin submission to anthropics/claude-plugins-community (community marketplace launched 2026-05-22; the plugin package itself — .claude-plugin/plugin.json + .mcp.json — lives at repo root and is validated by CI; the remaining step is the operator-side submission via clau.de/plugin-directory-submission); App Schemas codegen (WWDC 2026 introduced App Schemas — a new agentic layer over App Intents + App Entities, plus a View Annotations API for on-screen awareness and an App Intents Testing framework; the installed SDK exposes the non-deprecated @AppIntent(schema:) / @AppEntity(schema:) / @AppEnum(schema:) macro declarations, and full Xcode can typecheck those macros, but the default Command Line Tools still lack AppIntentsMacros / AppIntentsTesting; Calendar events, Reminders, and Contacts also lack matching public AssistantSchemas constants in the local SDK, so AirMCP keeps the generated default artifact on plain AppIntents/AppEntities until CI has a schema-capable toolchain and each mapping targets an official schema constant). iOS companion server (ios/Sources/AirMCPServer, ~1500 LOC) is preview, not GA — macOS is the shipping surface.
• Design intent — Core infra (HITL · audit · rate-limit · HMAC chain · network policy · OAuth scope gate) is the differentiated layer; the tool surface is broad and JXA-thin by design. JXA is the bridge, not the product. The interesting code lives in src/shared/ (audit, rate-limit, HITL, network policy, OAuth gate, structured-content validators) and the Swift bridges (swift/Sources/AirMCPKit) for EventKit / HealthKit / PhotoKit / Vision / FoundationModels. Blast-radius unit is one tool call. Adjacent to — not a replacement for — the canonical Model Context Protocol reference servers (Everything, Filesystem, Fetch, Git, Memory, Sequential Thinking, Time); AirMCP fills the Apple-native domain those references leave open. Aligned with Anthropic's three-layer containment doctrine (How we contain Claude across products, 2026-05-27 engineering blog): the Environment layer (sandbox / VM / egress controls) and Model layer (system prompts / classifiers) are Anthropic's host-side responsibility; AirMCP implements the External Content layer — tool-permission gating + MCP server auditing — for the Apple-native domain, complementary to (not replacing) Claude Code's process-level Seatbelt/bubblewrap sandbox. The same production governance primitives (sensitive-action HITL, scope-gated permissions, real-time tamper-evident audit, rate-limited destructive ops, emergency stop file) that high-stakes vertical MCP servers — financial trading, crypto exchange, supply-chain attestation — build per-deployment are surfaced once here as OSS reference.
• Non-goals — Per-session batched approval that covers "the next N calls" (failure mode this project is built around). Editable or skippable audit entries (the chain is load-bearing). Promising iOS parity on the public surface (preview only). Replacing native Apple apps — AirMCP automates them, it does not reimplement them. Headless / non-Apple platforms beyond what Google Workspace already provides.
• Redacted — External persons, accounts, and any internal-case identifiers are deliberately omitted. Self-critical metrics ("wrapper percentage", coverage-as-quality) are not surfaced as positioning.

Features

• 295 tools (31 modules) — Apple app CRUD + system control + Apple Intelligence + UI Automation + Screen Capture + Maps + Podcasts + Weather + iWork (Pages/Numbers/Keynote) + Google Workspace + dynamic shortcuts + context memory + audit introspection
• Profile-first runtime — starter, communications-safe, productivity, and full module profiles, plus progressive / profile / full tool exposure so clients can start thin and expand intentionally
• DLC-like module packs — npx airmcp modules or AIRMCP_MODULE_PACKS=core,productivity activates only selected packs; list_module_packs and profile_status.modulesMissingPacks make missing-pack state visible over MCP
• Task-scoped tool sessions — start_tool_session lets a client give one task a short-lived tool allowlist; discover_tools and run_tool honor that sessionId so a broad runtime can still feel narrow in use
• 232 Shortcuts / Siri AppIntents — auto-generated from the tool manifest (83 Interactive Snippet views + 13 AppEnum pickers); workflow-first AppShortcuts ship by default, while AskAirMCPIntent is a FoundationModels preview gated behind AIRMCP_ENABLE_FOUNDATION_MODELS
• 32 prompts + 14 YAML skill built-ins — per-app workflows + cross-module + developer workflows + Skills DSL (inputs / parallel / loop / on_error / retry / 9 event triggers)
• 9 MCP resources — Notes, Calendar, Reminders, Music, Mail, System, Context Memory + unified context://snapshot/{depth}
• 3 interactive MCP Apps — calendar_week_view, music_player, timeline_today (fuses events + reminders on one day-axis)
• 9 event triggers — calendar, reminders, pasteboard, mail unread, focus mode, now playing, file modified, screen locked/unlocked — skills bind to any of these for automation
• Safety first — HITL approval + audit log + rate limit (60/min + 10 destructive/hr) + emergency stop file + allowNetwork inbound HTTP exposure policy (RFC 0002)
• OAuth 2.1 + Resource Indicators — RFC 0005 Steps 1+2: with-oauth* inbound HTTP policy, JWT verification (RS256/ES256 only, 60s clock tolerance), scope gate (mcp:read / mcp:write / mcp:destructive / mcp:admin), .well-known/oauth-protected-resource per RFC 9728, zero-interaction local dev via npm run dev:oauth. Browser MCP clients: see docs/oauth-browser-pkce.md for the Authorization Code + PKCE setup
• Sessionless discovery — .well-known/mcp.json publishes the active advertised tool surface, enabled module inventory, network policy, allowed origins, and authorization mode so registry crawlers (Anthropic MCP Registry, Smithery, PulseMCP, Glama) catalog AirMCP without opening a session
• JXA + Swift 6.2 bridge — JXA for basic automation, Swift 6 strict concurrency with EventKit/PhotoKit/HealthKit/Vision, plus opt-in FoundationModels previews
• Apple Intelligence preview — On-device summarize / rewrite / proofread / ai_agent / ai_plan_metrics (planner regression catcher) via Foundation Models. This path is macOS 26+ / Apple Silicon and compile-time opt-in (AIRMCP_ENABLE_FOUNDATION_MODELS). WWDC 2026 made the model layer officially pluggable: Foundation Models gained a LanguageModel protocol where on-device, Private Cloud Compute, and third-party cloud models back the same session API — Anthropic and Google publish Swift packages for their frontier models (WWDC26 session 241, first-party). Apple's own announcement names no Siri backbone vendor — the widely reported Gemini deal is press reporting, not Apple's wording — and AirMCP doesn't bet on one either way: the governance layer (sensitive-action HITL, HMAC-chained audit, scope gate, rate limits) is model-agnostic, and the brains stay in whatever MCP client you connect.
• Context memory — memory_put/query/forget/stats + memory://recent resource for facts/entities/episodes, surviving restarts
• Native menubar app — SwiftUI companion with onboarding wizard, auto-start, log viewer, update notifications, permission setup, server crash auto-restart, and app-owned loopback HTTP runtime for clients that should not each launch their own AirMCP server. Current release builds are ad-hoc signed; Developer ID codesigning + notarization (Gatekeeper-green) are wired in .github/workflows/release-app.yml but gated on Apple signing secrets, so they have not shipped yet.
• One-click setup — setup_permissions tool or menubar app to request all macOS permissions at once
• Dual transport — stdio (default) + HTTP/SSE (--http) with token auth, origin allow-list, and startup invariants that refuse to boot misconfigured servers

Get Started

Two paths. The menubar app is the recommended local runtime: start AirMCP.app once, then point Claude, Codex, Cursor, Windsurf, or other clients at that same loopback server. Claude Desktop users can also get one-click install via .mcpb, which is convenient but launches under Claude Desktop rather than the AirMCP.app-owned runtime.

Option A — Claude Desktop one-click install (recommended for non-devs)

1. Download airmcp-<version>.mcpb from Releases.
2. Drag it onto Claude Desktop, or Settings → Extensions → Install from file….
3. Fill in the config form (Gemini API key optional; modules toggle). Click Install.

Full walkthrough: docs/mcpb.md.

Option B — CLI wizard (2 minutes)

1. Install Node.js — brew install node or nodejs.org.

2. Run the Setup Wizard:

npx airmcp init

Picks the modules to enable, writes the MCP-client config, saves preferences to ~/.config/airmcp/config.json.

Non-interactive setup:

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

3. Restart your MCP client. Your AI can now read notes, manage reminders, check your calendar, and more.

Troubleshooting

npx airmcp doctor

Checks Node.js version, config files, MCP client setup, macOS permissions, and module status — all in one command.

Module add-ons

npx airmcp modules
npx airmcp modules enable productivity,communications
npx airmcp modules enable productivity --install
npx airmcp modules uninstall media
npx airmcp modules doctor

This edits the runtime modulePacks activation set. --install installs the matching companion npm add-on into ~/.airmcp/addons (override with AIRMCP_ADDON_INSTALL_PREFIX) and then activates the pack; uninstall disables the pack and removes that companion package. The npm and MCPB release artifacts ship as a slim root, while npm run addons:build stages tarball-ready physical add-on packages from dist, npm run addons:verify-install proves installed add-ons are load-bearing in external-only mode, and npm run addons:measure-split records the slim-root size/startup delta against the universal local build. Add-on package names intentionally omit pack-* naming, for example @heznpc/airmcp-productivity.

Inbound webhooks & Power Automate (opt-in)

Two network-facing modules stay off in every profile — including full — until you enable them explicitly. They give AirMCP a bridge to the Windows/cloud side without a Mac-as-server backend, and they are gated this way because they are the only surfaces that accept inbound traffic or trigger external flows.

• webhooks (AIRMCP_ENABLE_WEBHOOKS=true) — AirMCP's other nine event sources all observe the local Mac (calendar, clipboard, focus, files…). This one lets the outside world push an event to a skill. webhook_listen_start opens a loopback HTTP listener; each verified POST becomes a webhook_received event, and a skill with trigger.event: webhook_received acts on it. webhook_listen_stop / webhook_listen_status manage it. Safety defaults: binds 127.0.0.1 only, optional HMAC-SHA256 over x-airmcp-signature, a 1 MiB body cap (413 on overflow), and any non-loopback bind requires a ≥32-char secret. The listener replies 202 on a verified request; the skill runs asynchronously.
• powerautomate (AIRMCP_ENABLE_POWERAUTOMATE=true) — cloudflow_trigger POSTs to a Power Automate Cloud Flow HTTP trigger URL (SAS sig param or OAuth Bearer), with a hard 120 s timeout (the Cloud Flow Response action cap) and a streamed response-size cap so a misconfigured flow can't OOM an agent loop.

Together they close the round trip: a skill fires a Cloud Flow with cloudflow_trigger, the flow does Windows-side work, then POSTs back to the webhook listener, which emits webhook_received for a follow-up skill. Both remain governed by the same HITL approval, HMAC-chained audit log, rate limits, and network policy as every other AirMCP tool.

OAuth footgun — a Cloud Flow HTTP trigger's OAuth scope must use a double slash before .default: https://service.flow.microsoft.com//.default. A single slash returns MisMatchingOAuthClaims, because the audience URL itself ends with /.

Workflow Catalog

npx airmcp workflows
npx airmcp workflows daily-briefing --prompt

Shows the target workflows AirMCP is built around — prompts, Siri phrases, core tools, and safety notes. See docs/workflows.md for the target users, workflow catalog, and product direction behind this list.

The macOS menubar app exposes the same workflow catalog under Workflows, so non-CLI users can copy the right prompt or Siri phrase without reading the docs.

Try It — Apple Workspace Workflows

Once connected, just ask your AI in natural language. Here are some things you can try:

Daily Command Briefing

• "Brief me on today's calendar, overdue reminders, unread mail, and recent notes"
• "Turn today's meetings into a prep checklist"
• "Summarize what changed since yesterday and save it as a note"

Inbox → Tasks

• "Find emails from Alex about the project and create reminders for action items"
• "Draft replies for urgent mail, but ask before sending anything"
• "Move newsletters out of the inbox and keep only messages that need action"

Meeting Prep

• "For my next meeting, find related notes, contacts, files, and reminders"
• "Create a meeting agenda in Notes from recent mail and project notes"
• "After this meeting, turn the notes into follow-up reminders"

Research → Output

• "Open the Apple developer docs in Safari and summarize the page"
• "Search my Safari tabs for that article I was reading about Swift"
• "Find the Q1 report, read it, and draft a summary email to the team"

Siri and Shortcuts

• "Hey Siri, Daily Briefing in AirMCP"
• "Hey Siri, triage my inbox with AirMCP"
• "Hey Siri, Ask AirMCP about my day" (FoundationModels opt-in build only)

Power User

• "Turn on dark mode, set volume to 50%, and lower brightness"
• "Take a screenshot and save it to my Desktop"
• "Run my 'Morning Routine' shortcut"

These are the first-class use cases. The full tool catalog stays available when you need to compose something more specific.

Why AirMCP?

AirMCP is a shared action layer, not a tool collection. Siri and Shortcuts give Apple-native entry points; Claude, Codex, Cursor, Raycast, and other MCP clients bring external agents; AirMCP gives all of them the same governed runtime for Apple workspace actions. The value lives below the tool surface:

• Workflow engine — declare multi-step automations in YAML with parallel / loop / on_error / retry / 9 event triggers. Not one-shot tool calls — a runtime that orchestrates.
• Semantic memory — facts / entities / episodes with Gemini or on-device Swift embeddings. Persistent across restarts. This is agent context, not an OS feature.
• Safety primitives — HITL approval, HMAC-chained audit log with tamper-detection asserted as a tested contract (tests/audit-tamper-detection.test.js), rate limiting, emergency stop, OAuth 2.1 + Resource Indicators (production-grade JWT verifier with RS256/ES256 + RFC 8707 audience + RFC 9728 protected-resource metadata + DPoP advertisement).
• Native Swift bridge (optional — build from source with npm run swift-build; not shipped in the npm tarball or the .mcpb bundle) — direct access to EventKit / HealthKit / PhotoKit / Vision, with Foundation Models behind the explicit AIRMCP_ENABLE_FOUNDATION_MODELS preview flag. Not an osascript wrapper.
• Multi-client by design — the same workflows can be reached from Siri/Shortcuts via AppIntents and from Claude, Codex, opencode, Gemini CLI, Antigravity, Cursor, Zed, Cline, JetBrains Air, OpenClaw, ChatGPT MCP Apps, and any future MCP-capable AI. No per-client porting.

What AirMCP is — and isn't

Is: the governed action layer for AI on Apple. Siri can understand the request; AirMCP gives it hands, memory, workflows, and guardrails. External MCP agents use the same runtime through stdio or HTTP. When Apple ships more native action APIs, AirMCP can delegate lower-level app calls to the OS while keeping the orchestration and governance layer above.

Isn't: a thin per-app wrapper. The distinctive thing is integrated depth — 295 tools + Swift bridge + Skills DSL + production-grade safety primitives + Google Workspace + iOS AppIntents in one auditable open-source codebase, with the governance layer (sensitive-action HITL, HMAC-chained audit, scope gate, rate limit) as the load-bearing part, not the tool count.

Integrated depth

The point is the combination in one auditable codebase, not any single capability:

• 295 tools across 31 modules — Apple app CRUD + system control + Apple Intelligence + iWork + Google Workspace + dynamic Shortcuts.
• Skills DSL workflow engine — parallel / loop / on_error / retry / 9 event triggers.
• Semantic memory — Gemini + on-device Swift embeddings, persistent across restarts.
• Production safety primitives — HITL for destructive and other configured sensitive actions, HMAC-chained audit log (tamper-detection asserted in tests/audit-tamper-detection.test.js), rate limiting, emergency stop, OAuth 2.1 + Resource Indicators (RS256/ES256 JWT + RFC 8707 audience + RFC 9728 PRM + DPoP advertisement). DPoP is advertised in the .well-known card, not enforced — dpop_bound_access_tokens_required: false; tokens are not yet bound to a proof.
• Input validation — Zod on every tool + outputSchema on reads + script↔schema contract tests.
• Native Swift API depth — direct EventKit / HealthKit / PhotoKit / Vision, plus opt-in Foundation Models preview builds; not an osascript wrapper.
• iOS surface — 232 auto-generated AppIntents + AppShortcutsProvider (RFC 0007); AskAirMCPIntent is present only in AIRMCP_ENABLE_FOUNDATION_MODELS builds on iOS 26+/macOS 26+.
• 9-language i18n, multi-client (any MCP-capable AI), open source (every line auditable, modifiable, forkable).

Why this position holds

• Tool surface is leverage, not the moat. Apple's eventual system MCP will replace many AppleScript wrappers; AirMCP's workflow engine + safety + memory + multi-client + Google Workspace layer survives as the integration above the OS.
• Open source: every line auditable, modifiable, forkable. Apple's closed alternative won't have this.
• Sustained development on integrated depth: actively maintained at v2.12+ with a CI-gated release pipeline, 1900+ test assertions, and the governance layer kept under tamper-detection contracts — depth that compounds over time rather than a one-shot tool dump.
• WWDC 2026 validated the category (keynote 2026-06-08; App Schemas session 240 + agentic-security session 347, both first-party; full analysis in docs/rfc/0011-post-wwdc-2026.md). Apple deprecated SiriKit and made App Intents the mandatory — and only — way a third-party app reaches Siri, then layered App Schemas on top for agentic, cross-app, onscreen-aware actions. AirMCP already auto-generates App Intents (RFC 0007), so it was on the one blessed path before Apple made it mandatory. Apple's own agentic-security session now tells developers to add user confirmation for sensitive actions, authentication, and prompt-injection containment — the exact governance AirMCP has shipped from day one. And Apple drew a two-layer line: the consumer/Siri path is App Intents (Apple-proprietary, Siri-only) — no consumer MCP — while at the developer/agent layer Apple ratified MCP (Xcode 27 takes "skills, MCP tools and any agent via the Agent Client Protocol"; Xcode is itself an MCP server via xcrun mcpbridge). So MCP is now Apple's blessed agent-tool interface, and every non-Siri agent — Claude, Codex, opencode, Gemini CLI, Cursor, Zed, Cline, ChatGPT MCP Apps, and Apple's own Xcode — acts through MCP. Apple owns the default assistant; AirMCP is the open action runtime for every other AI client — one governed catalog feeding both the App Intents (Siri) surface and the MCP surface.

Skills DSL

Declare a multi-step workflow in YAML and expose it as an MCP prompt or tool. The executor handles error policy, retries, parallel fan-out, loops, runtime arguments, and event triggers.

name: sender-to-tasks
title: Sender → Tasks
expose_as: tool

inputs:
  query: { type: string, default: newsletter }
  mailbox: { type: string, default: INBOX }
  limit: { type: number, default: 10 }

steps:
  - id: hits
    tool: search_messages
    args: { query: "{{query}}", mailbox: "{{mailbox}}", limit: "{{limit}}" }
    retry: 2
    retry_backoff_ms: 1000

  - id: queue
    tool: create_reminder
    only_if: "{{hits}} != null"
    loop: "{{hits}}"
    on_error:
      continue # per-iteration: a HITL denial on one item
      # doesn't abort the rest of the batch
    args:
      title: "Follow up: {{_item.subject}}"
      body: "From {{_item.sender}} (query: {{query}})"

Built-in skills (14): morning-briefing, calendar-alert, inbox-triage, meeting-action-items, focus-guardian, skills-weekly-review, project-digest, weekly-digest-note, focus-block-planner, clipboard-url-to-reading, favorites-digest, sender-to-tasks, evening-winddown, daily-journal.

Event triggers: calendar_changed, reminders_changed, pasteboard_changed, mail_unread_changed, focus_mode_changed, now_playing_changed, file_modified, screen_locked, screen_unlocked.

User-authored skills land in ~/.config/airmcp/skills/*.yaml and hot-reload.

Safety & Operations

AirMCP can register up to 295 tools on your machine. The default starter/progressive surface exposes only a small front door, and these layers keep a buggy agent plan from turning into an incident:

• HITL approval — at the default level, every sensitive or destructive tool prompts before firing (via MCP Elicitation or a Unix socket fallback). Per-call, per-scope.
• Rate limit — 60 tool calls/minute globally, 10 destructive/hour. Token-bucket so bursts are fine; sustained rate isn't.
• Emergency stop — touch ~/.config/airmcp/emergency-stop blocks every destructive tool immediately with a 1-second probe cache. No restart needed. rm the file to resume.
• Audit log — every tool call lands in ~/.airmcp/audit.jsonl with PII-scrubbed args, 0600 perms, 10MB rotation. Query it via audit_log / audit_summary tools. Each entry carries an HMAC chain (single-line tamper detection — AIRMCP_AUDIT_HMAC_KEY for cross-machine integrity) and a correlation ID that threads the entry, any thrown error, and the OpenTelemetry span (when enabled) for the same call — so a failing tool can be traced across log lines with one grep. Every env knob lives in docs/environment.md (77 vars indexed by category).
• Inbound HTTP exposure policy (RFC 0002) — AIRMCP_ALLOW_NETWORK = loopback-only (default) / with-token / with-token+origin / with-oauth / with-oauth+origin / unauthenticated. This controls who can reach AirMCP's HTTP server; it is not a general outbound egress allow-list (the only outbound-side filtering is the Safari URL guard on open_url/add_to_reading_list, which rejects non-http(s) schemes and loopback/RFC1918/link-local destinations). Startup invariant refuses to boot a misconfigured server. Reverse-proxy header detection warns when a loopback-only server sees X-Forwarded-* so silently-public deploys get caught.
• npx airmcp doctor — runs all the above policy + macOS compatibility + permission checks in one command.

Siri · Shortcuts · Spotlight (iOS 17+ / macOS 14+)

AirMCP's tools auto-register as Apple App Intents — 231 generated intents across read + non-destructive write surfaces (RFC 0007 Phase A). Destructive intents are env-gated (AIRMCP_APPINTENTS_DESTRUCTIVE=true opt-in). Anything that speaks the Intents system — Siri, Shortcuts, Spotlight, the Action Button, Widgets — calls them directly without opening the app.

• Workflow-first Siri phrases ship out of the box via AppShortcutsProvider (codegen'd from the MCP tool manifest). The default provider uses nine workflow/read shortcuts; the optional Ask AirMCP natural-language shortcut is compiled separately when FoundationModels are enabled.
• Shortcuts app: every AirMCP tool appears as an action with typed parameters.
• iOS 26 "Use Model": autonomously picks AirMCP tools as tool-call targets.
• Interactive Snippets (iOS 26+): 83 typed tools render SwiftUI result views inline in Shortcuts/Siri/Spotlight.
• "Ask AirMCP" preview (iOS 26+/macOS 26+, opt-in build): natural-language agent routed to Apple's on-device Foundation Models with AirMCP tools registered. 100% on-device, but not part of the default Swift build.

See docs/shortcuts.md for the full guide + RFC 0007 for the architecture.

Client Setup

Works with any MCP-compatible client. Start AirMCP.app first; it owns the local Apple permissions and starts a token-gated HTTP runtime on http://127.0.0.1:3847/mcp. Stdio-only clients use npx -y airmcp connect as a proxy into that runtime with AIRMCP_HTTP_TOKEN set. The app and setup wizard generate the per-install token at ~/Library/Application Support/AirMCP/http-token.

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "airmcp": {
      "command": "npx",
      "args": ["-y", "airmcp", "connect", "--url", "http://127.0.0.1:3847/mcp"],
      "env": {
        "AIRMCP_HTTP_TOKEN": "<token>"
      }
    }
  }
}

Claude Code

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

Codex

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

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "airmcp": {
      "command": "npx",
      "args": ["-y", "airmcp", "connect", "--url", "http://127.0.0.1:3847/mcp"],
      "env": {
        "AIRMCP_HTTP_TOKEN": "<token>"
      }
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "airmcp": {
      "command": "npx",
      "args": ["-y", "airmcp", "connect", "--url", "http://127.0.0.1:3847/mcp"],
      "env": {
        "AIRMCP_HTTP_TOKEN": "<token>"
      }
    }
  }
}

Other MCP Clients

Any client that supports the MCP stdio transport can use AirMCP. Use npx -y airmcp connect --url http://127.0.0.1:3847/mcp with AIRMCP_HTTP_TOKEN set when AirMCP.app owns the runtime. Direct HTTP clients must send Authorization: Bearer <token>. Use direct npx -y airmcp only when you intentionally want that client process to own a separate server instance; npx airmcp init --client-runtime direct and npx airmcp connect-clients --client-runtime direct write that shape explicitly.

Local Development

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

Developer Testing

npm run dev:test -- notes             # test one module (fast, in-process)
npm run dev:test:changed              # test only git-changed modules
npm run dev:test:watch -- notes       # watch mode: auto re-test on save
npm run dev:test -- --tool list_notes # test a single tool

See Testing & Debugging Guide for the full testing workflow.

Menubar App (Optional)

A native SwiftUI companion app for server status monitoring and permission setup.

cd app && swift build -c release
# Binary: app/.build/release/AirMCPApp

Features: onboarding wizard, auto-start on login, log viewer, update notifications, server status, one-click permission setup, MCP client config clipboard copy.

HTTP Mode

HTTP server mode for remote agents, registries, and multi-client setups:

npx airmcp --http --port 3847

• Endpoint: POST/GET/DELETE /mcp
• Transport: Streamable HTTP + SSE (MCP spec 2025-11-25)
• Session management via Mcp-Session-Id header
• Default port: 3847
• Startup policy invariant (RFC 0002): refuses to bind public interfaces without a token — see Safety & Operations above.

Useful for running a Mac Mini as an "always-on AI hub."

Claude in Chrome & other browser-based MCP clients

Browser extensions — including Anthropic's Claude in Chrome — can't spawn stdio subprocesses, so they consume MCP over HTTP. AirMCP's HTTP transport is designed for exactly this case.

1 · Start AirMCP with a token + origin allow-list:

# Generate a token and keep it — you'll paste it into the Chrome extension.
export AIRMCP_HTTP_TOKEN=$(openssl rand -hex 32)

# Only accept requests whose Origin matches Claude's web UI:
export AIRMCP_ALLOWED_ORIGINS="https://claude.ai"

# Declarative policy: external binding, token required, Origin allow-list enforced.
export AIRMCP_ALLOW_NETWORK="with-token+origin"

npx airmcp --http --bind-all --port 3847

2 · In the browser extension's MCP settings, add:

3 · Verify wiring:

# From the same machine — should return the server card JSON:
curl http://127.0.0.1:3847/.well-known/mcp.json

The response includes "network_policy": "with-token+origin" so the client can confirm what it's connecting to before a single tool call. Registry crawlers (Anthropic MCP Registry, Smithery, PulseMCP, Glama) use the same endpoint to build their catalog without connecting live — it carries the full tool inventory (tools.count, tools.names), enabled modules, license, and homepage, so a crawler can surface "AirMCP: 295 tools across calendar, notes, mail, …" without opening a session. MCP spec version pinned via schema_version: "2025-11-25". When the policy is with-oauth*, a sibling /.well-known/oauth-protected-resource endpoint (RFC 9728) advertises the authorization server + audience + supported scopes so conforming clients can negotiate OAuth before the first MCP call.

Running AirMCP on a laptop that suspends? Put the menubar app on your Mac Mini / always-on host, point the browser at that hostname, and leave the token in Chrome's secure storage. Revoke by rotating AIRMCP_HTTP_TOKEN and restarting the server.

Security gotchas — in order of "most likely to bite":

• Don't put AirMCP behind a proxy that strips X-Forwarded-* without also switching to AIRMCP_ALLOW_NETWORK=with-token. AirMCP detects proxy headers and warns, but only when it's in loopback-only mode — flip the policy first.
• Don't hand-edit origin lists into "*" — the Origin check is your last line of defence if a token leaks from the extension's storage.
• touch ~/.config/airmcp/emergency-stop on the server blocks every destructive call within 1s, no restart needed. Remember this path.

Tools

Notes (12 tools)

Reminders (11 tools)

Calendar (10 tools)

Contacts (10 tools)

Mail (11 tools)

Music (17 tools)

Finder (8 tools)

Safari (12 tools)

System (27 tools)

Photos (9 tools)

Messages (6 tools)

Shortcuts (11 tools)

UI Automation (10 tools)

Apple Intelligence (13 tools)

Requires macOS 26+ with Apple Silicon and a Swift bridge built with AIRMCP_ENABLE_FOUNDATION_MODELS.

Context Memory (4 tools)

Durable on-disk store for facts, named entities, and time-anchored episodes. Backed by ~/.cache/airmcp/memory.json; also exposed as the memory://recent MCP resource.

Audit (2 tools)

Consumable view of the on-device audit log (populated for every tool call).

TV (6 tools)

Screen Capture (5 tools)

Maps (8 tools)

Podcasts (6 tools)

⚠️ Deprecated on macOS 26+ — Apple removed the entire Podcasts JXA scripting dictionary in Tahoe. The module is skipped at registration on macOS 26+ (manifest brokenOn: [26]); still available on macOS ≤ 25. Scheduled for removal at v3.0.0.

Weather (3 tools)

Location (2 tools)

Bluetooth (4 tools)

Google Workspace (16 tools)

Requires: npm install -g @googleworkspace/cli && gws auth setup

Resources

MCP resources provide live data from Apple apps via URI.

Prompts

Per-App

• organize-notes — Classify notes by topic, create folders, move
• find-duplicates — Find similar notes, compare, suggest cleanup
• weekly-review — Summarize past week's notes
• organize-reminders — Scan, identify overdue/completed, cleanup
• daily-review — Today's due reminders with priorities
• schedule-review — Upcoming events, conflicts, optimizations
• meeting-prep — Event details + related notes for meeting prep

Cross-Module

• daily-briefing — Today's events + due reminders + recent notes
• weekly-digest — Past N days: events + notes + reminders combined
• meeting-notes-to-reminders — Extract action items from meeting notes, create reminders
• event-follow-up — Create follow-up note and reminders after a meeting
• research-with-safari — Safari research + save results to Notes
• focus-session — Calendar + Reminders + Music focus session
• file-organizer — Finder file organization + Notes logging

Developer Workflows

• dev-session — Scan project, check specs, research docs, create session notes
• debug-loop — Capture errors from Safari/clipboard, locate code, log bugs, create fix tasks
• screen-capture-flow — Screenshot → Photos import → annotation notes
• app-release-prep — Calendar schedule + Notes changelog + Reminders checklist
• idea-to-task — Break idea into tasks → Reminders + Calendar time blocks
• build-log — Analyze build output, log errors or celebrate success

Shortcuts

• shortcut-automation — Discover and chain Siri Shortcuts for automation
• shortcut-discovery — Find relevant shortcuts for a task
• shortcut-troubleshooting — Debug and fix broken shortcuts

Developer Agent Pipeline

AirMCP's developer prompts connect Apple apps into autonomous agent workflows. Each prompt orchestrates tools across multiple modules — AI reads the actual filesystem, Notes, Calendar, and Reminders for context, then records structured results.

┌─────────────────────────────────────────────────────────────────┐
│                     dev-session                                 │
│  Finder (scan) → Notes (specs) → Safari (docs) → Notes (log)   │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│                     debug-loop                                  │
│  Safari (JS errors) → Clipboard → Finder (locate) →            │
│  Notes (bug log) → Reminders (fix tasks)                        │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│                     idea-to-task                                 │
│  Notes (idea) → AI (decompose) → Reminders (tasks) →           │
│  Calendar (time blocks)                                         │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│                     build-log                                   │
│  Finder (output) → Clipboard (log) →                            │
│  ┌ Fail → Notes (error log) → Reminders (fix tasks)             │
│  └ Pass → Notification → Music (celebrate) → Notes (success)    │
└─────────────────────────────────────────────────────────────────┘

Designed for AI coding agents (Claude Code, Cursor, Copilot, etc.) to invoke via MCP prompts, turning your Mac into a context-aware development environment.

Module Presets

By default, new installations start with 7 starter modules (Notes, Reminders, Calendar, Shortcuts, System, Finder, Weather) to keep things simple. You can enable more anytime:

# Re-run the setup wizard to change modules
npx airmcp init

# Or request every installed module at once
npx airmcp --full

Or edit ~/.config/airmcp/config.json directly:

{
  "disabledModules": ["messages", "intelligence"]
}

CLI Commands

Configuration

Environment Variables

Experimental profile-only modules are not enabled by --full / AIRMCP_FULL. Enable them explicitly with AIRMCP_PROFILE=<module> or their dedicated AIRMCP_ENABLE_<MODULE> flag.

Config File

~/.config/airmcp/config.json:

{
  "disabledModules": ["messages", "intelligence"],
  "includeShared": false,
  "allowSendMessages": false,
  "allowSendMail": false,
  "hitl": {
    "level": "sensitive-only",
    "timeout": 30
  }
}

Human-in-the-Loop (HITL)

Require manual approval before sensitive or destructive operations:

{
  "hitl": {
    "level": "sensitive-only",
    "timeout": 30
  }
}

Levels: off, destructive-only, sensitive-only, all-writes, all

Semantic Search (Optional)

On-device cross-app semantic search powered by Apple's NLContextualEmbedding. Find related notes, events, reminders, and emails by meaning — not just keywords.

npm run swift-build  # Build the Swift bridge first

Then use the tools:

1. semantic_index — Index data from enabled Apple apps into a local vector store
2. semantic_search — Search by meaning across all indexed data
3. find_related — Find items related to a specific note/event/reminder
4. semantic_status — Check index status

Supports Korean, English, Japanese, Chinese with automatic language detection. Optionally set GEMINI_API_KEY for higher-quality Google Gemini embeddings.

Swift Bridge (Optional)

For semantic search, recurring events/reminders (EventKit), and photo import/delete (PhotoKit):

npm run swift-build

FoundationModels-backed Apple Intelligence is a preview path. Build it explicitly with a macOS 26 SDK and the opt-in compile flag:

cd swift
swift build -c release -Xswiftc -DAIRMCP_ENABLE_FOUNDATION_MODELS

Requirements

• macOS
• Node.js >= 20
• Per-app automation permissions (prompted on first run) — use setup_permissions tool to request all at once
• Apple Intelligence preview: macOS 26+ with Apple Silicon and AIRMCP_ENABLE_FOUNDATION_MODELS

Limitations

Modules with OS requirements (e.g., Intelligence requires macOS 26+) are automatically disabled at startup on older systems via runtime OS detection.

Architecture & Security

• JXA/AppleScript dependency — Core automation relies on Apple's scripting dictionaries. While these have been stable for 10+ years, macOS updates can theoretically break individual modules. Circuit breaker (3 failures → 60s auto-disable) isolates failures. UI Automation tools (6 tools) are inherently more brittle and separated into their own module.
• Input sanitization — open_url and add_to_reading_list reject non-http(s) URL schemes and SSRF-style destinations (loopback, RFC1918, link-local / cloud-metadata) via validateExternalHttpUrl. run_javascript is off unless explicitly enabled (AIRMCP_ALLOW_RUN_JAVASCRIPT) and returns its output as untrusted content. escJxaShell/escAS strip control characters from shell/AppleScript arguments.
• Read data exposure — At the default sensitive-only HITL level, destructive operations and privacy-sensitive reads (incl. mail/messages/contacts content, clipboard, health, precise location) require per-call HITL approval; only non-sensitive reads run without a prompt. When connected to cloud LLMs, returned data passes through the LLM provider. Mitigations: PII scrubbing in logs, pagination limits, sensitive modules (mail, messages) require explicit opt-in.
• IPC overhead — Multi-process path (Client → Node.js → osascript/Swift CLI → macOS app). Each JXA call adds ~50ms overhead. Pagination prevents bulk data transfers. Swift bridge path bypasses JXA for EventKit/PhotoKit operations.
• Scope — 295 tools across 31 modules follow 5 repeating patterns (JXA CRUD, Swift bridge, HTTP API, System Events, CLI wrapper), keeping maintenance proportional to pattern count, not tool count.

Location & Bluetooth

• Location requires macOS Location Services permission (first use triggers system dialog).
• Bluetooth scanning discovers BLE (Low Energy) devices only. Classic Bluetooth devices are listed via list_bluetooth_devices in the System module.
• Bluetooth connect/disconnect operates within the server process lifecycle.

Notes

• Move copies and deletes (new ID, reset dates, lost attachments). Update replaces entire body — read first to preserve content.
• Password-protected notes cannot be read.

Reminders / Calendar

• JXA recurrence is read-only — use create_recurring_event/create_recurring_reminder (Swift/EventKit).
• Calendar attendees are read-only.

Contacts

• Custom fields not accessible.

Mail

• Content truncated to 5000 chars by default (maxLength parameter adjustable).

Messages

• Individual message content (chat history) not accessible via JXA.
• Send requires recipient to be a registered buddy in Messages.

Music

• Smart playlists are read-only.
• Queue manipulation not available.

Finder

• Tags use Spotlight (mdfind), performance varies with index state.

Safari

• Reading page content requires "Allow JavaScript from Apple Events" in Safari Developer menu.
• run_javascript is disabled unless AIRMCP_ALLOW_RUN_JAVASCRIPT=true (or allowRunJavascript in config); its output is returned as untrusted content. URL-scheme and SSRF rejection (non-http(s), loopback/RFC1918/link-local) applies to open_url and add_to_reading_list, not to run_javascript.
• macOS 26+: Bookmark and Reading List tools (list_bookmarks, list_reading_list, add_bookmark) use Bookmarks.plist instead of JXA (Apple removed bookmark scripting). Requires Full Disk Access for your terminal in System Settings > Privacy & Security. add_bookmark is not supported on macOS 26+.

Podcasts

• macOS 26+: Apple removed the entire Podcasts JXA scripting dictionary in Tahoe. The module is skipped at registration time via compatibility.brokenOn: [26] in src/shared/modules.ts — tools/list won't surface any *_podcast_* tools on Tahoe hosts, so models can't pick a tool that can never succeed. Surfaced through airmcp doctor and print-compat-report. Scheduled for removal at v3.0.0; replacement under investigation (Shortcuts bridge / Media framework).

Photos

• JXA: album creation and photo addition only, no import/delete.
• Swift bridge (macOS 26+): full import/delete via PhotoKit.

Pages / Numbers / Keynote

• macOS 26+: Apple renamed iWork apps (e.g. "Pages" → "Pages Creator Studio"). AirMCP uses bundle IDs internally so this is handled transparently.
• Requires the corresponding iWork app to be open for document operations.

Apple Intelligence

• Requires macOS 26 (Tahoe) + Apple Silicon.
• Build the bridge with cd swift && swift build -c release -Xswiftc -DAIRMCP_ENABLE_FOUNDATION_MODELS.

Roadmap

v2.1 (Current)

• Gemini Embedding 2 — gemini-embedding-2-preview로 업그레이드. 네이티브 멀티모달(텍스트/이미지/오디오/비디오) 3072차원 임베딩. on-device Swift bridge + cloud Gemini 하이브리드 provider 지원. (WWDC26부터 Apple Foundation Models도 LanguageModel 프로토콜로 서드파티 클라우드 모델 — Anthropic·Google Swift 패키지 — 을 공식 지원, 하이브리드 구성이 플랫폼 표준 패턴이 됨)
• Google Workspace — Gmail, Drive, Sheets, Calendar, Docs, Tasks, People via @googleworkspace/cli
• Dynamic module loading — New modules = 1 line in MANIFEST (no import boilerplate)
• Centralized constants — All API URLs, timeouts, buffer sizes in src/shared/constants.ts with env var overrides

v2.0

• CoreLocation — Native GPS coordinates via Swift/CLLocationManager
• CoreBluetooth — BLE device scanning, state, connect/disconnect via Swift/CBCentralManager
• App Management — Launch, quit, check app status
• Window Management — List, move, resize, minimize windows across all apps
• Geocoding — Forward/reverse geocoding via Open-Meteo and Nominatim APIs
• Security hardening — Sensitive modules (mail, messages) opt-in by default, architecture limitations documented

Platform Constraints (macOS 26+)

• Safari bookmarks/reading list — Apple removed JXA bookmark scripting classes in macOS 26. The plist fallback (~/Library/Safari/Bookmarks.plist) requires Full Disk Access, which TCC blocks for headless/direct MCP server processes. The app-owned runtime is the intended permission boundary, but signed-app runtime verification is still required for this surface. Investigating Shortcuts-based or WebExtension bridge approaches.
• Safari add_bookmark — Legacy JXA make new bookmark no longer supported in macOS 26. No programmatic alternative available yet.
• Podcasts — Apple removed the Podcasts JXA scripting dictionary entirely in macOS 26. All 6 Podcasts tools return errors. Investigating Shortcuts bridge or Media framework alternatives.

Future

• OAuth 2.1 browser PKCE flow guide — RFC 0005 Step 3: docs for Managed Agents / Claude in Chrome clients (Steps 1+2 shipped in v2.11.0)
• Stateless streamable HTTP — horizontal scale per MCP 2026 roadmap (session state externalized)
• iOS / visionOS exploration (v3.0+)
• Consolidated registry re-publishing — single self-publishing PR that re-pushes the current .well-known/mcp.json manifest + mcpName to Anthropic MCP Registry, Smithery, PulseMCP, Glama, MCP Market, Cline Marketplace, LobeHub. Past ad-hoc registrations exist on some of these but versions and metadata have drifted out of date; until the re-push lands, only the discovery endpoint itself (published on this server) reflects current state.

Contributing

See CONTRIBUTING.md for development setup, code style, and PR guidelines.

First-time contributors: look for issues labeled good first issue.

Community

• GitHub Discussions — Questions, ideas, show & tell
• Issues — Bug reports and feature requests
• Changelog — Release history

License

MIT