AirMCP

Open action runtime for Apple-native agents. 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, opencode, Gemini CLI, Antigravity, Cursor, Zed, Cline, JetBrains Air, OpenClaw, and Xcode 27 agents (which speak MCP since 26.3) — 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 (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; AirMCP already auto-generates 232 App Intents via RFC 0007, and scripts/gen-swift-intents.mjs will be extended to emit App Schemas + expanded entity shapes once the session videos and developer docs publish — see docs/rfc/0011-post-wwdc-2026.md). 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 (per-call 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

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+). Confirmed at WWDC 2026 (June 8): Siri's new agentic stack runs on a Gemini backbone via Private Cloud Compute. AirMCP's two-track design — Swift FoundationModels for on-device + Gemini embeddings (semantic memory) — already matches that split, so the transition needs no migration.
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. 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. 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)

Download airmcp-<version>.mcpb from Releases.
Drag it onto Claude Desktop, or Settings → Extensions → Install from file….
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 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 — direct access to EventKit / HealthKit / PhotoKit / Vision / Foundation Models. Not an osascript wrapper.
Multi-client by design — same server works for Claude, Codex, opencode, Gemini CLI, Antigravity (Google I/O 2026 CLI + desktop), 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 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: a thin per-app wrapper. The distinctive thing is integrated depth — 272 tools + Swift bridge + Skills DSL + production-grade safety primitives + Google Workspace + iOS AppIntents in one auditable open-source codebase, with the governance layer (per-call 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:

272 tools across 29 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 — per-call HITL, 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 / Foundation Models, not an osascript wrapper.
iOS surface — 232 auto-generated AppIntents + AppShortcutsProvider (RFC 0007); AskAirMCPIntent → Foundation Models tool calling (iOS 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 per-call user confirmation, 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 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:

Field	Value
Server URL	`http://<your-mac>:3847/mcp` (or `https://…` behind a TLS-terminating proxy)
Auth header	`Authorization: Bearer <AIRMCP_HTTP_TOKEN>`
Transport	Streamable HTTP (SSE)

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)

Tool	Description	Type
`list_notes`	List all notes with title, folder, dates	read
`search_notes`	Search by keyword in title and body	read
`read_note`	Read full content by ID	read
`create_note`	Create a note with HTML body	write
`update_note`	Replace entire body	destructive
`delete_note`	Delete (moved to Recently Deleted)	destructive
`move_note`	Move to another folder	destructive
`list_folders`	List folders with note counts	read
`create_folder`	Create a new folder	write
`scan_notes`	Bulk scan with metadata and preview	read
`compare_notes`	Compare 2-5 notes side by side	read
`bulk_move_notes`	Move multiple notes at once	destructive

Reminders (11 tools)

Tool	Description	Type
`list_reminder_lists`	List all lists with counts	read
`list_reminders`	Filter by list/completed	read
`read_reminder`	Full details by ID	read
`create_reminder`	Create with due date/priority	write
`update_reminder`	Update properties	destructive
`complete_reminder`	Mark complete/incomplete	write
`delete_reminder`	Delete permanently	destructive
`search_reminders`	Search by keyword in name/body	read
`create_reminder_list`	Create a new reminder list	write
`delete_reminder_list`	Delete a reminder list	destructive
`create_recurring_reminder`	Create with recurrence rule (Swift/EventKit)	write

Calendar (10 tools)

Tool	Description	Type
`list_calendars`	List calendars with name/color	read
`list_events`	Events in date range with pagination	read
`read_event`	Full details with attendees	read
`create_event`	Create with location/description	write
`update_event`	Update properties	destructive
`delete_event`	Delete permanently	destructive
`search_events`	Keyword search in date range	read
`get_upcoming_events`	Next N events from now	read
`today_events`	All events for today	read
`create_recurring_event`	Create with recurrence rule (Swift/EventKit)	write

Contacts (10 tools)

Tool	Description	Type
`list_contacts`	List with email/phone, pagination	read
`search_contacts`	Search by name, email, phone, or org	read
`read_contact`	Full details (emails, phones, addresses)	read
`create_contact`	Create with email/phone/org	write
`update_contact`	Update properties	destructive
`delete_contact`	Delete permanently	destructive
`list_groups`	List contact groups	read
`add_contact_email`	Add email to existing contact	write
`add_contact_phone`	Add phone to existing contact	write
`list_group_members`	List contacts in a group	read

Mail (11 tools)

Tool	Description	Type
`list_mailboxes`	List mailboxes with unread counts	read
`list_messages`	Recent messages in a mailbox	read
`read_message`	Full message content	read
`search_messages`	Search by subject/sender	read
`mark_message_read`	Mark read/unread	write
`flag_message`	Flag/unflag a message	write
`get_unread_count`	Total unread across all mailboxes	read
`move_message`	Move message to another mailbox	destructive
`list_accounts`	List all mail accounts	read
`send_mail`	Compose and send an email	write
`reply_mail`	Reply to an email message	write

Music (17 tools)

Tool	Description	Type
`list_playlists`	List playlists with track counts	read
`list_tracks`	Tracks in a playlist	read
`now_playing`	Current track and playback state	read
`playback_control`	Play, pause, next, previous	write
`search_tracks`	Search by name/artist/album	read
`play_track`	Play a specific track by name	write
`play_playlist`	Start playing a playlist	write
`get_track_info`	Detailed track metadata	read
`set_shuffle`	Set shuffle and repeat mode	write
`create_playlist`	Create a new playlist	write
`add_to_playlist`	Add a track to a playlist	write
`remove_from_playlist`	Remove a track from a playlist	destructive
`delete_playlist`	Delete an existing playlist	destructive
`get_rating`	Get rating, favorited, and disliked status	read
`set_rating`	Set star rating (0-100) for a track	write
`set_favorited`	Mark or unmark a track as favorited	write
`set_disliked`	Mark or unmark a track as disliked	write

Finder (8 tools)

Tool	Description	Type
`search_files`	Spotlight file search	read
`get_file_info`	File info (size, dates, tags)	read
`set_file_tags`	Set Finder tags	destructive
`recent_files`	Recently modified files	read
`list_directory`	List files in directory	read
`move_file`	Move/rename file	destructive
`trash_file`	Move to Trash	destructive
`create_directory`	Create new directory	write

Safari (12 tools)

Tool	Description	Type
`list_tabs`	List tabs across all windows	read
`read_page_content`	Read page text content	read
`get_current_tab`	Current active tab URL/title	read
`open_url`	Open URL in Safari	write
`close_tab`	Close a specific tab	destructive
`activate_tab`	Switch to a specific tab	write
`run_javascript`	Execute JavaScript in tab	write
`search_tabs`	Search tabs by title/URL	read
`list_bookmarks`	List all bookmarks across folders	read
`add_bookmark`	Add a bookmark to Safari	write
`list_reading_list`	List Reading List items	read
`add_to_reading_list`	Add URL to Reading List	write

System (27 tools)

Tool	Description	Type
`get_clipboard`	Read clipboard content	read
`set_clipboard`	Write to clipboard	write
`get_volume`	Get system volume	read
`set_volume`	Set system volume	write
`toggle_dark_mode`	Toggle dark/light mode	write
`get_frontmost_app`	Get frontmost application	read
`list_running_apps`	List running applications	read
`get_screen_info`	Display information	read
`show_notification`	Show system notification	write
`capture_screenshot`	Capture screenshot (full/window/selection)	write
`get_wifi_status`	WiFi connection status and signal	read
`toggle_wifi`	Turn WiFi on or off	write
`list_bluetooth_devices`	List paired Bluetooth devices	read
`get_battery_status`	Battery percentage, charging, time remaining	read
`get_brightness`	Get display brightness level	read
`set_brightness`	Set display brightness level	write
`toggle_focus_mode`	Toggle Do Not Disturb on or off	write
`system_sleep`	Put system to sleep	write
`prevent_sleep`	Keep system awake for N seconds	write
`system_power`	Shutdown or restart the system	destructive
`launch_app`	Launch/activate an application	write
`quit_app`	Quit a running application	destructive
`is_app_running`	Check if an application is running	read
`list_all_windows`	List all windows across all apps	read
`move_window`	Move a window to specific coordinates	write
`resize_window`	Resize a window	write
`minimize_window`	Minimize or restore a window	write

Photos (9 tools)

Tool	Description	Type
`list_albums`	List albums	read
`list_photos`	List photos in album	read
`search_photos`	Search photos by keyword	read
`get_photo_info`	Photo metadata details	read
`list_favorites`	List favorite photos	read
`create_album`	Create new album	write
`add_to_album`	Add photo to album	write
`import_photo`	Import photo from file (Swift/PhotoKit)	write
`delete_photos`	Delete photos by ID (Swift/PhotoKit)	destructive

Messages (6 tools)

Tool	Description	Type
`list_chats`	Recent conversations with participants	read
`read_chat`	Chat details (participants, last update)	read
`search_chats`	Search by name/participant/handle	read
`send_message`	Send iMessage/SMS text	write
`send_file`	Send file via iMessage/SMS	write
`list_participants`	List chat participants	read

Shortcuts (11 tools)

Tool	Description	Type
`list_shortcuts`	List available shortcuts	read
`run_shortcut`	Run shortcut by name	write
`search_shortcuts`	Search shortcuts by name	read
`get_shortcut_detail`	Shortcut details/actions	read
`create_shortcut`	Create a new shortcut via UI automation	write
`delete_shortcut`	Delete shortcut by name (macOS 13+)	destructive
`export_shortcut`	Export shortcut to .shortcut file	write
`import_shortcut`	Import shortcut from .shortcut file	write
`edit_shortcut`	Open shortcut in Shortcuts app for editing	write
`duplicate_shortcut`	Duplicate an existing shortcut	write

UI Automation (10 tools)

Tool	Description	Type
`ui_open_app`	Open app and read accessibility summary	read
`ui_click`	Click element by coordinates or text	write
`ui_type`	Type text into focused field	write
`ui_press_key`	Send key combinations	write
`ui_scroll`	Scroll in direction	write
`ui_read`	Read app accessibility tree	read
`ui_accessibility_query`	Query UI elements by role/title/value/identifier	read
`ui_perform_action`	Find element by locator + perform AX action	write
`ui_traverse`	BFS traverse with PID targeting + visible filter	read
`ui_diff`	Compare UI state before/after an action	read

Apple Intelligence (13 tools)

Requires macOS 26+ with Apple Silicon.

Tool	Description	Type
`summarize_text`	On-device text summarization	read
`rewrite_text`	Rewrite with specified tone	read
`proofread_text`	Grammar/spelling correction	read
`generate_text`	Generate text with custom instructions via on-device AI	read
`generate_structured`	Generate structured JSON output with schema	read
`tag_content`	Content classification/tagging with confidence	read
`ai_chat`	Named multi-turn on-device AI session	read
`generate_image`	Generate an image on disk via Image Playground	write
`scan_document`	Detect text / tables / forms in an image	read
`generate_plan`	Ask the on-device model for a JSON tool-call plan	read
`ai_plan_metrics`	Run a sampled GOLDEN_PLANS batch and report planner quality	read
`ai_status`	Check Foundation Model availability	read
`ai_agent`	On-device autonomous tool-calling agent	read

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.

Tool	Description	Type
`memory_put`	Insert or update a fact / entity / episode (idempotent upsert, optional TTL)	write
`memory_query`	Filter by kind / tags / substring, newest-first	read
`memory_forget`	Delete by id / key / tag	destructive
`memory_stats`	Counts by kind + oldest/newest timestamps (sweeps expired as a side-effect)	read

Audit (2 tools)

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

Tool	Description	Type
`audit_log`	Paginated recent calls, filterable by tool / status / time window	read
`audit_summary`	Total count, error rate, top-N busiest tools over a window	read

TV (6 tools)

Tool	Description	Type
`tv_list_playlists`	List Apple TV playlists (library)	read
`tv_list_tracks`	List movies/episodes in playlist	read
`tv_now_playing`	Currently playing content	read
`tv_playback_control`	Play/pause/next/previous control	write
`tv_search`	Search movies/TV shows	read
`tv_play`	Play movie/episode by name	write

Screen Capture (5 tools)

Tool	Description	Type
`capture_screen`	Capture full screen screenshot (returns PNG image)	read
`capture_window`	Capture a specific app window	read
`capture_area`	Capture a screen region by coordinates	read
`list_windows`	List all visible windows with position/size	read
`record_screen`	Record screen for 1-60 seconds (.mov)	write

Maps (8 tools)

Tool	Description	Type
`search_location`	Search for a place in Apple Maps	write
`get_directions`	Get directions between two locations	write
`drop_pin`	Drop a pin at specific coordinates	write
`open_address`	Open a specific address in Apple Maps	write
`search_nearby`	Search for places near a location	write
`share_location`	Generate a shareable Apple Maps link	read
`geocode`	Convert place name/address to coordinates	read
`reverse_geocode`	Convert coordinates to place name/address	read

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.

Tool	Description	Type
`list_podcast_shows`	List subscribed podcast shows	read
`list_podcast_episodes`	List episodes for a show	read
`podcast_now_playing`	Currently playing podcast episode	read
`podcast_playback_control`	Play, pause, next, previous	write
`play_podcast_episode`	Play a specific episode by name	write
`search_podcast_episodes`	Search episodes by keyword	read

Weather (3 tools)

Tool	Description	Type
`get_current_weather`	Get current weather by coordinates	read
`get_daily_forecast`	Get multi-day forecast by coordinates	read
`get_hourly_forecast`	Get hourly forecast by coordinates	read

Location (2 tools)

Tool	Description	Type
`get_current_location`	Get device's current GPS coordinates	read
`get_location_permission`	Check Location Services authorization status	read

Bluetooth (4 tools)

Tool	Description	Type
`get_bluetooth_state`	Check Bluetooth power state	read
`scan_bluetooth`	Scan for nearby BLE devices	read
`connect_bluetooth`	Connect to a BLE device by UUID	write
`disconnect_bluetooth`	Disconnect a BLE device	write

Google Workspace (16 tools)

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

Tool	Description	Type
`gws_status`	Check GWS CLI availability	read
`gws_gmail_list`	List Gmail messages with query	read
`gws_gmail_read`	Read Gmail message by ID	read
`gws_gmail_send`	Send email via Gmail	write
`gws_drive_list`	List Google Drive files	read
`gws_drive_read`	Get Drive file metadata	read
`gws_drive_search`	Full-text search across Drive	read
`gws_sheets_read`	Read Google Sheet values	read
`gws_sheets_write`	Write to Google Sheet	write
`gws_calendar_list`	List Google Calendar events	read
`gws_calendar_create`	Create Google Calendar event	write
`gws_docs_read`	Read Google Doc content	read
`gws_tasks_list`	List Google Tasks	read
`gws_tasks_create`	Create Google Task	write
`gws_people_search`	Search Google Contacts	read
`gws_raw`	Execute any GWS CLI command	write

Resources

MCP resources provide live data from Apple apps via URI.

URI	Description
`notes://recent`	10 most recent notes
`notes://recent/{count}`	Recent notes (custom count, max 50)
`calendar://today`	Today's calendar events
`calendar://upcoming`	Next 7 days of calendar events
`reminders://due`	Overdue reminders
`reminders://today`	Today's due reminders (incomplete only)
`music://now-playing`	Currently playing Apple Music track
`system://clipboard`	macOS clipboard content
`mail://unread`	Unread mail count across all mailboxes
`context://snapshot`	Unified context from all active apps
`context://snapshot/{depth}`	Configurable depth context (brief/standard/full)

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

Command	Description
`npx airmcp init`	Interactive setup wizard
`npx airmcp doctor`	Diagnose installation issues
`npx airmcp`	Start MCP server (stdio, default)
`npx airmcp --version`	Print version and exit
`npx airmcp --full`	Start with all 27 modules enabled
`npx airmcp --http`	Start as HTTP server (port 3847)

Configuration

Environment Variables

Variable	Default	Description
`AIRMCP_INCLUDE_SHARED`	`false`	Include shared notes/folders
`AIRMCP_ALLOW_SEND_MESSAGES`	`false`	Allow sending iMessages (opt-in)
`AIRMCP_ALLOW_SEND_MAIL`	`false`	Allow sending emails (opt-in)
`AIRMCP_FULL`	`false`	Enable all modules (ignores preset)
`AIRMCP_DISABLE_{MODULE}`	—	Disable a specific module (e.g. `AIRMCP_DISABLE_MUSIC=true`)
`GEMINI_API_KEY`	—	Google Gemini API key for cloud embeddings (optional)
`AIRMCP_EMBEDDING_MODEL`	`gemini-embedding-2-preview`	Gemini embedding model name
`AIRMCP_EMBEDDING_DIM`	`3072`	Embedding dimension (256/512/1024/2048/3072)
`AIRMCP_EMBEDDING_PROVIDER`	auto	Force provider: `gemini`, `swift`, `hybrid`, `none`
`AIRMCP_HTTP_TOKEN`	—	Bearer token for HTTP mode authentication

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:

semantic_index — Index data from enabled Apple apps into a local vector store
semantic_search — Search by meaning across all indexed data
find_related — Find items related to a specific note/event/reminder
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+: 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 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+)
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

AirMCP

AirMCP Overview

What is AirMCP about?

How to use AirMCP?

Key features of AirMCP

Use cases of AirMCP

FAQ from the AirMCP

AirMCP's README

AirMCP

What this is — at a glance

Features

Get Started

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

Option B — CLI wizard (2 minutes)

Troubleshooting

Try It — Talk to Your Mac

Why AirMCP?

What AirMCP is — and isn't

Integrated depth

Why this position holds

Skills DSL

Safety & Operations

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

Client Setup

Claude Desktop

Claude Code

Cursor

Windsurf

Other MCP Clients

Local Development

Developer Testing

Menubar App (Optional)

HTTP Mode

Claude in Chrome & other browser-based MCP clients

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)

Context Memory (4 tools)

Audit (2 tools)

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)

Resources

Prompts

Per-App

Cross-Module

Developer Workflows

Shortcuts

Developer Agent Pipeline

Module Presets

CLI Commands

Configuration

Environment Variables

Config File

Human-in-the-Loop (HITL)

Semantic Search (Optional)

Swift Bridge (Optional)

Requirements

Limitations

Architecture & Security

Location & Bluetooth

Notes

Reminders / Calendar