AirMCP

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.

Client Setup

Works with any MCP-compatible client. Examples:

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.

Re-run the setup wizard to change modules

npx airmcp init

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.

Menubar App (Optional)

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

```bash cd app && swift build -c release

Configuration

Environment Variables

Config File

~/.config/airmcp/config.json:

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

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.

```bash npm run swift-build # Build the Swift

CLI Commands

Generate a token and keep it — you'll paste it into the Chrome extension.

export AIRMCP_HTTP_TOKEN=$(openssl rand -hex 32)

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

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:

```bash

Or enable all modules at once

npx airmcp --full

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

Troubleshooting

npx airmcp doctor

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