AirMCP

Apple-native agent runtime for any MCP client. Skills DSL workflow engine, semantic memory, OAuth 2.1, HMAC-chained audit log — over native Swift bridges into EventKit, HealthKit, PhotoKit, Vision, and Foundation Models. 272 tools across 29 Apple + Google Workspace modules. Connect Claude, Codex, Gemini, Cursor, JetBrains Air, OpenClaw — any MCP-capable AI.

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

Requires: macOS for the server. Apple Intelligence features (ai_agent, summarize, etc.) require macOS 26+ on Apple Silicon. Most tools work on macOS 14+.

Available in multiple languages at the project landing page.

What this is — at a glance

• Currently implemented — 272 tools across 29 modules; HMAC-chained audit log with tamper-detection test suite; HITL approval per destructive call; rate limit (60/min + 10 destructive/hr); allowNetwork declarative HTTP 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 tool manifest; native SwiftUI menubar app (codesigned + notarized).

• Planned — RFC 0005 Step 3 browser PKCE guide; stateless streamable HTTP for horizontal scale per MCP 2026 roadmap; iOS/visionOS exploration (v3.0+); marketplace listings on MCP Market, Cline, LobeHub. 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.

• 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

• 272 tools (29 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

• 232 Shortcuts / Siri AppIntents — auto-generated from the tool manifest (50 Interactive Snippet views + 17 AppEnum pickers); AskAirMCPIntent natural-language agent on iOS 26+/macOS 26+ via FoundationModels

• 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 declarative HTTP policy (RFC 0002)

• OAuth 2.1 + Resource Indicators — RFC 0005 Steps 1+2: with-oauth* network 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 full tool + 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/FoundationModels

• Apple Intelligence — On-device summarize / rewrite / proofread / ai_agent / ai_plan_metrics (planner regression catcher) — all via Foundation Models (macOS 26+)

• 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. Codesigned + notarized release builds ship Gatekeeper-green.

• 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. Claude Desktop users get one-click install via .mcpb. Everyone else uses the CLI wizard.

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.

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.

Try It — Talk to Your Mac

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

Everyday

• "Read my latest notes and summarize them"

• "What's on my calendar today?"

• "Show me overdue reminders and reschedule them to tomorrow"

• "Play some jazz on Apple Music"

Productivity

• "Draft a meeting agenda in Notes, then create calendar events for each topic"

• "Find all emails from Alex about the project and create reminders for action items"

• "Search my contacts for everyone at Acme Corp"

System Control

• "Turn on dark mode, set volume to 50%, and lower brightness"

• "Take a screenshot and save it to my Desktop"

• "What apps are running right now? Quit anything I'm not using"

Research & Web

• "Open the Apple developer docs in Safari and summarize the page"

• "Search my Safari tabs for that article I was reading about Swift"

Power User

• "Scan nearby Bluetooth devices"

• "Get my current GPS coordinates and show the weather here"

• "Record my screen for 10 seconds"

• "Run my 'Morning Routine' shortcut"

Cross-App Workflows

• "Check today's meetings, find related notes, and create a prep checklist in Reminders"

• "Search my files for the Q1 report, read it, and draft a summary email to the team"

These are just starting points — with 272 tools across 29 Apple apps, the combinations are endless.

Why AirMCP?

AirMCP is a runtime layer, not a tool collection. The 272 tools operate on Apple data; the workflow engine + memory + safety operate on the tools. The value lives below the tool surface in infrastructure Apple won't ship in their own MCP API:

• Skills DSL 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 (88% coverage on safety-critical files), 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 — direct access to EventKit / HealthKit / PhotoKit / Vision / Foundation Models. Not an osascript wrapper.

• Multi-client by design — same server works for Claude, Codex, Gemini, Cursor, JetBrains Air, OpenClaw, ChatGPT (MCP Apps), and any future MCP-capable AI. No per-client porting.

What AirMCP is — and isn't

Is: the runtime layer for AI agents on Apple. When Apple ships their system MCP API (likely partial, focused on user-facing CRUD), AirMCP's tool surface gets delegated to the OS — and the runtime layer above stays. Apple Notes / Reminders / Calendar are the bottom; AirMCP's value is the middle.

Isn't: "the only Apple MCP server." LMCP (92 tools), Apple-PIM-Agent-Plugin, and ~100 narrower Apple MCPs exist. What's distinctive is integrated depth: 272 tools + Swift bridge + Skills DSL + production-grade safety primitives + Google Workspace + iOS AppIntents — all in one auditable open-source codebase.

Comparison vs other approaches

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.

• First-mover momentum on integrated depth: research from Apr 2026 notes — "Outside the archived apple-mcp, no implementation exceeds 5 stars. Most have single-digit commits and single contributors." AirMCP holds the slot with active development at v2.12+.

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 runs with access to 272 tools on your machine. A few layers keep a buggy agent plan from turning into an incident:

• HITL approval — every 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).

• HTTP network policy (RFC 0002) — AIRMCP_ALLOW_NETWORK = loopback-only (default) / with-token / with-token+origin / unauthenticated. 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 — 232 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.

• Top-10 Siri phrases ship out of the box via AppShortcutsProvider (codegen'd from the MCP tool manifest).

• 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+): 50 typed tools render SwiftUI result views inline in Shortcuts/Siri/Spotlight.

• "Ask AirMCP" (iOS 26+/macOS 26+): natural-language agent routed to Apple's on-device Foundation Models with AirMCP tools registered. 100% on-device.

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

Client Setup

Works with any MCP-compatible client. Examples:

Claude Desktop

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

{
  "mcpServers": {
    "airmcp": {
      "command": "npx",
      "args": ["-y", "airmcp"]
    }
  }
}

Claude Code

claude mcp add airmcp -- npx -y airmcp

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "airmcp": {
      "command": "npx",
      "args": ["-y", "airmcp"]
    }
  }
}

Windsurf

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

{
  "mcpServers": {
    "airmcp": {
      "command": "npx",
      "args": ["-y", "airmcp"]
    }
  }
}

Other MCP Clients

Any client that supports the MCP stdio transport can use AirMCP. Use npx -y airmcp as the server command.

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

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)

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 5 core modules (Notes, Reminders, Calendar, Shortcuts, System) to keep things simple. You can enable more anytime:

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

# Or enable all modules at once
npx airmcp --full

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

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

CLI Commands

Configuration

Environment Variables

Config File

~/.config/airmcp/config.json:

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

Human-in-the-Loop (HITL)

Require manual approval before destructive operations:

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

Levels: off, destructive-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), photo import/delete (PhotoKit), and Apple Intelligence — requires macOS 26+:

npm run swift-build

Requirements

• macOS

• Node.js >= 18

• Per-app automation permissions (prompted on first run) — use setup_permissions tool to request all at once

• Apple Intelligence: macOS 26+ with Apple Silicon

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 — run_javascript blocks javascript: and data: URL schemes to prevent code injection. escJxaShell strips control characters from shell arguments.

• Read data exposure — Destructive operations require HITL approval, but read operations (mail, messages, contacts) are not rate-limited. When connected to cloud LLMs, sensitive 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 — 272 tools across 29 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 rejects javascript: and data: URLs to prevent injection attacks.

• 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+: All Podcasts tools are non-functional. Apple removed the Podcasts scripting dictionary in macOS 26 (Tahoe). The circuit breaker will auto-disable the module after 3 failures.

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 bridge binary with npm run swift-build.

Roadmap

v2.1 (Current)

• Gemini Embedding 2 — Apple Intelligence의 Gemini 채택에 맞춰 gemini-embedding-2-preview로 업그레이드. 네이티브 멀티모달(텍스트/이미지/오디오/비디오) 3072차원 임베딩. on-device Swift bridge + cloud Gemini 하이브리드 provider 지원. Apple이 Foundation Models에 Gemini를 도입하면서 AirMCP도 동일 생태계로 확장

• 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 MCP server processes. 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+)

• Marketplace listings — MCP Market, Cline Marketplace, LobeHub (Anthropic MCP Registry + Smithery + PulseMCP + Glama already live)

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