orchard-mcp

MCP server for local macOS apps and files using native frameworks.

Gives any MCP-compatible client (Warp, Claude Desktop, Claude Code, Cursor) structured access to Apple Calendar, Mail, Reminders, Notes, Contacts, Files, Numbers, Pages, and Keynote. There are no cloud dependencies and no OAuth setup: data comes from the local macOS stores and apps already configured on your machine.

How it works

orchard-mcp reads from local macOS data stores and apps:

• EventKit for Calendar and Reminders
• Contacts.framework for Contacts
• FileManager, Spotlight, PDFKit, and Vision for files and text extraction
• AppleScript/JXA for Mail, Notes, Numbers, Pages, and Keynote

The OS handles account authentication through System Settings > Internet Accounts. orchard-mcp itself never communicates with any remote service and requires no OAuth client IDs, redirect URIs, or token management.

Privacy note: orchard-mcp itself sends no data anywhere. However, the MCP client that invokes tools receives the returned data (calendar events, emails, reminders, files, notes, contacts, and documents) as part of the conversation context. Be mindful of what you ask the client to access.

App Safety

orchard-mcp refuses broad requests rather than making host apps unresponsive. Mail.app, Notes, Numbers, Pages, and Keynote calls are serialized through app-specific safety lanes with timeout, queue, and output-size budgets. Expensive scopes are rejected before AppleScript/JXA starts.

Examples:

• mail_save_attachment requires account and mailbox from a recent Mail result.
• Notes body/all search is refused; use title search, then notes_read_note.
• numbers_read and numbers_get_formulas require a cell range.
• PNG/JPEG Keynote export requires a single slide index.
• Calendar list/search ranges are capped at 31 days.

See docs/app-safety-audit.md for the current audit and guardrails.

The only permissions needed are macOS TCC grants (for example, “Allow access to Calendars”), triggered automatically on first use or during setup.

Status

Current release: 65 tools across Calendar, Mail, Reminders, Files, System, Numbers, Pages, Keynote, Notes, and Contacts. See CHANGELOG.md for release history.

Requirements

• macOS 14+ (Sonoma or later)
• Node.js 22+

Install

npm install -g @l22-io/orchard-mcp
orchard-mcp setup

If Xcode Command Line Tools are installed (xcode-select --install), postinstall builds apple-bridge from source - the strongest install-time guarantee. Otherwise the package falls back to the shipped prebuilt universal binary (arm64 + x86_64) and verifies its SHA-256 against the manifest published inside the tarball.

The setup wizard verifies prerequisites, triggers macOS permission prompts, and generates MCP client configuration.

From Source

See CONTRIBUTING.md for building from source.