AirMCP

AirMCP

MCP server for the entire Apple ecosystem — Notes, Reminders, Calendar, Contacts, Mail, Messages, Music, Finder, Safari, System, Photos, Shortcuts, Apple Intelligence, TV, Screen Capture, Maps, and Podcasts. Connect any AI to your Mac.

Available in multiple languages at the project landing page.

Features

• 173 tools (18 modules) — Apple app CRUD + system control + Apple Intelligence + UI Automation + Screen Capture + Maps + Podcasts + dynamic shortcuts
• 29 prompts — per-app workflows (notes, calendar, reminders, shortcuts) + cross-module + developer workflows
• 11 MCP resources — Notes, Calendar, Reminders live data URIs
• JXA + Swift bridge — JXA for basic automation, EventKit/PhotoKit for advanced features
• Recurring events/reminders — EventKit recurrence rules (macOS 26+ Swift bridge)
• Photo import/delete — PhotoKit photo management (macOS 26+ Swift bridge)
• Apple Intelligence — On-device summarize, rewrite, proofread (macOS 26+)
• Native menubar app — SwiftUI companion with onboarding wizard, auto-start, log viewer, update notifications, permission setup
• One-click setup — setup_permissions tool or menubar app to request all macOS permissions at once
• Dual transport — stdio (default, safe local) + HTTP/SSE (--http) for remote agents and registries
• Safety annotations — readOnly/destructive hints on all tools

Get Started (2 minutes)

1. Install Node.js

If you don't have Node.js, install it first:

# Using Homebrew (recommended)
brew install node

# Or download from https://nodejs.org (LTS version)

2. Run the Setup Wizard

npx airmcp init

This will:

• Let you choose which Apple apps to connect (Notes, Calendar, Reminders, etc.)
• Automatically configure your MCP client
• Save your preferences to ~/.config/airmcp/config.json

3. Restart Your MCP Client

That's it! Your AI can now read your 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.

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

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 2024-11-05)
• Session management via Mcp-Session-Id header
• Default port: 3847

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

Tools

Notes (12 tools)

Reminders (11 tools)

Calendar (10 tools)

Contacts (10 tools)

Mail (11 tools)

Music (13 tools)

Finder (8 tools)

Safari (12 tools)

System (17 tools)

Photos (9 tools)

Messages (6 tools)

Shortcuts (10 tools)

UI Automation (6 tools)

Apple Intelligence (8 tools)

Requires macOS 26+ with Apple Silicon.

TV (6 tools)

Screen Capture (5 tools)

Maps (6 tools)

Podcasts (6 tools)

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": true,
  "allowSendMail": true,
  "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.

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.

Photos

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

Apple Intelligence

• Requires macOS 26 (Tahoe) + Apple Silicon.
• Build bridge binary with npm run swift-build.

Roadmap

v1.6.0 (Current)

• Progress notifications — record_screen, semantic_index report real-time progress via notifications/progress
• MCP Elicitation — Protocol-native user confirmation (form mode), falls back to socket HITL for older clients
• Server Card — GET /.well-known/mcp.json discovery endpoint for Claude, VS Code Copilot, etc.
• Mail pagination — list_messages now supports offset parameter, response matches {total, offset, returned} pattern
• Swift stdin validation — MAX_STDIN_SIZE (50MB) guard on bridge input

v1.7 (Planned)

• OAuth 2.1 + PKCE — HTTP transport authentication for remote deployments
• Async Tasks — Long-running operations return handles with progress streaming
• MCP Registry — Official registry.modelcontextprotocol.io submission

Future

• GUI .app distribution (Code Signing + Notarization, Homebrew Cask)
• iOS / visionOS exploration (v2.0+)

License

MIT