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, Podcasts, Weather, Pages, Numbers, Keynote, Location, and Bluetooth. Connect any AI to your Mac.

Available in multiple languages at the project landing page.

Features

• 252 tools (25 modules) — Apple app CRUD + system control + Apple Intelligence + UI Automation + Screen Capture + Maps + Podcasts + Weather + iWork (Pages/Numbers/Keynote) + Google Workspace + dynamic shortcuts

• 30 prompts — per-app workflows (notes, calendar, reminders, shortcuts) + cross-module + developer workflows + YAML skills

• 11 MCP resources — Notes, Calendar, Reminders, Music, Mail, System 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.

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 252 tools across 25 Apple apps, the combinations are endless.

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 (17 tools)

Finder (8 tools)

Safari (12 tools)

System (27 tools)

Photos (9 tools)

Messages (6 tools)

Shortcuts (10 tools)

UI Automation (10 tools)

Apple Intelligence (8 tools)

Requires macOS 26+ with Apple Silicon.

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.

• 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 — 252 tools across 25 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.

• 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 upgrade — Apple Intelligence의 Gemini 채택에 맞춰 text-embedding-004로 업그레이드. on-device Swift bridge + cloud Gemini 하이브리드 provider 지원. Apple이 Foundation Models에 Gemini를 도입하면서 AirMCP도 동일 생태계로 확장 — on-device 처리와 클라우드 임베딩을 자동 전환

• 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 — 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 + PKCE — HTTP transport authentication for remote deployments

• GUI .app distribution — Code Signing + Notarization, Homebrew Cask

• Marketplace listings — mcp.so, Smithery, and other MCP directories

• iOS / visionOS exploration (v3.0+)

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