Open Source / MCP Integration

Native macOS Integration for AI Agents

MCP server giving Claude direct access to 6 macOS apps. Three purpose-built backends. 25,000 lines of TypeScript and Swift. 95% test coverage.

View on GitHub npm Package

The Problem: Why macOS Integration Is Hard

There's no unified API for personal data on macOS. Each app stores data differently, uses different frameworks, and has different permission models.

Calendar + Reminders

Use EventKit, Apple's Swift framework. No JavaScript bindings exist. Requires compiled Swift binary.

Contacts + Notes

Scriptable via JXA (JavaScript for Automation). Underdocumented, fragile, but no compilation needed.

Messages + Mail

Store data in SQLite databases. Undocumented schema that changes between OS versions. No public API exists.

Permissions

Sandboxing and TCC permissions differ per app, per API, per OS version. Each backend needs different entitlements.

No existing tool unified all six apps reliably

The Architecture: Three Backends, One Principle

Each app stores data differently. Instead of forcing a single abstraction, we chose the right tool per app and unified behind MCP's tool protocol.

EventKit (Swift)

Calendar + Reminders

Apple's only sanctioned API for these apps. Compiled Swift helper binary communicates via JSON over stdout. The only backend requiring compiled code.

JXA (JavaScript)

Contacts + Notes

AppleScript dictionaries, no compilation needed. Underdocumented API handled with retry logic and error mapping.

SQLite (Direct)

Messages + Mail

No public API exists. Direct database reads of chat.db and Envelope Index. Handles schema differences across macOS versions. JXA alternatives are broken on Sonoma+.

Six Apps, Full Coverage

Complete read/write access to the macOS apps that hold your personal data.

📅
EventKit

Calendar

CRUD events, recurring schedules, attendees, multi-calendar support.

👤
JXA

Contacts

CRUD contacts, groups, property-level error handling.

💬
SQLite

Messages

Read iMessage and SMS conversations, attachment metadata.

📧
SQLite

Mail

Read emails across accounts, threading, folder structure.

📝
JXA

Notes

Read, create, and search notes across folders.

✅
EventKit

Reminders

CRUD with due dates, priorities, list management.

The Numbers

Built with the same evidence-based methodology we apply to every project.

893
Unit Tests
149
E2E Tests
95%
Coverage
25K
Lines of Code

Built in Public. Available for Consulting.

macos-mcp demonstrates how I approach complex integration problems. Choose the right tool per domain, test exhaustively, ship with confidence.

View on GitHub Back to Home