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.

MCP Client Configuration

Warp

Add as an MCP server in Warp settings with:

{"command": "npx", "args": ["@l22-io/orchard-mcp"]}

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "orchard": {
      "command": "npx",
      "args": ["@l22-io/orchard-mcp"]
    }
  }
}

Claude Code

claude mcp add --scope user orchard -- npx @l22-io/orchard-mcp

Cursor

Add to your MCP settings:

{"command": "npx", "args": ["@l22-io/orchard-mcp"]}

Available Tools

Calendar

• calendar.list_calendars - List all calendars with account, type, color
• calendar.list_events - Events in a date range (recurring events expanded)
• calendar.today - Today's events across all calendars
• calendar.search - Search events by title, notes, or location

Mail

• mail.list_accounts - List mail accounts with a bounded mailbox-name sample; use mail.unread_summary for unread counts
• mail.unread_summary - Unread count per account with recent message headers
• mail.search - Search messages by subject, sender, body, or all fields with pagination
• mail.read_message - Get message content by ID with configurable body truncation; pass account/mailbox locators when available
• mail.flagged - List flagged messages across all accounts with pagination
• mail.create_draft - Create a draft email in Mail.app for review
• mail.save_attachment - Save an email attachment to disk by message ID, index, account, and mailbox

Reminders

• reminders.list_lists - List all reminder lists with account, color, item count
• reminders.list_reminders - Reminders from a list with filters
• reminders.today - Incomplete reminders due today plus overdue reminders
• reminders.create_list - Create a new reminder list
• reminders.create_reminder - Create a reminder with optional due date, priority, notes
• reminders.complete_reminder - Mark a reminder as completed
• reminders.delete_reminder - Delete a reminder
• reminders.delete_list - Delete a reminder list

Files

• files.list - List directory contents with metadata
• files.info - Get detailed file metadata including Spotlight attributes
• files.search - Search files using macOS Spotlight
• files.read - Read or extract text from plain text, PDF, images, .docx, .rtf, .pages
• files.move - Move or rename files and folders, including batch operations
• files.copy - Copy a file or folder
• files.create_folder - Create a new directory
• files.trash - Move a file or folder to Trash

System

• system.doctor - Check permissions and list accessible accounts/apps

Numbers

• numbers.search - Find Numbers spreadsheets with Spotlight
• numbers.read - Read table data from a spreadsheet within a required cell range
• numbers.write - Write table data to a spreadsheet
• numbers.create - Create a new spreadsheet
• numbers.list_sheets - List sheets and tables
• numbers.add_sheet - Add a sheet
• numbers.remove_sheet - Remove a sheet
• numbers.get_formulas - Read formulas within a required cell range
• numbers.export - Export as CSV, PDF, or XLSX
• numbers.info - Inspect spreadsheet metadata

Pages

• pages.search - Find Pages documents with Spotlight
• pages.read - Read document text
• pages.write - Replace document text
• pages.create - Create a new document
• pages.find_replace - Find and replace text
• pages.insert_table - Insert table data
• pages.list_sections - List document sections
• pages.export - Export as PDF, DOCX, TXT, or EPUB
• pages.info - Inspect document metadata

Keynote

• keynote.search - Find Keynote decks with Spotlight
• keynote.read - Read slide content
• keynote.create - Create a new deck
• keynote.add_slide - Add a slide
• keynote.edit_slide - Edit slide title, body, or notes
• keynote.remove_slide - Remove a slide
• keynote.reorder_slides - Move slides
• keynote.list_slides - List slides
• keynote.list_themes - List available themes
• keynote.export - Export as PDF, PPTX, PNG, or JPEG; PNG/JPEG requires a slide index
• keynote.info - Inspect deck metadata

Notes

• notes.list_folders - List Notes folders
• notes.list_notes - List notes with optional folder filtering
• notes.search - Search notes by title; body/all search is refused for app safety
• notes.read_note - Read a note by ID

Contacts

• contacts.list_groups - List contact groups
• contacts.search - Search contacts
• contacts.read_contact - Read full contact details by ID

Architecture

Two-layer design:

1. TypeScript MCP server (src/) - handles MCP protocol over stdio, Zod schemas, and tool routing
2. Swift CLI (swift/) - native binary (apple-bridge) using macOS frameworks and app automation

The TypeScript layer spawns the Swift binary with child_process.spawn and parses JSON responses. All subcommands return a {"status": "ok"|"error", "data": ..., "error": ...} envelope.

apple-bridge normally runs from swift/.build/AppleBridge.app so macOS TCC grants are attached to the app bundle. Direct binary execution is still available through APPLE_BRIDGE_BIN for trusted custom installations.

Swift CLI Subcommands

apple-bridge calendars
apple-bridge events
apple-bridge search
apple-bridge mail-accounts
apple-bridge mail-unread
apple-bridge mail-search
apple-bridge mail-message
apple-bridge mail-flagged
apple-bridge mail-create-draft
apple-bridge mail-save-attachment
apple-bridge reminder-lists
apple-bridge reminders
apple-bridge reminders-today
apple-bridge reminder-create-list
apple-bridge reminder-create
apple-bridge reminder-complete
apple-bridge reminder-delete
apple-bridge reminder-delete-list
apple-bridge file-list
apple-bridge file-info
apple-bridge file-search
apple-bridge file-read
apple-bridge file-move
apple-bridge file-copy
apple-bridge file-create-folder
apple-bridge file-trash
apple-bridge doctor
apple-bridge numbers-search
apple-bridge numbers-read
apple-bridge numbers-write
apple-bridge numbers-create
apple-bridge numbers-list-sheets
apple-bridge numbers-add-sheet
apple-bridge numbers-remove-sheet
apple-bridge numbers-get-formulas
apple-bridge numbers-export
apple-bridge numbers-info
apple-bridge pages-search
apple-bridge pages-read
apple-bridge pages-write
apple-bridge pages-create
apple-bridge pages-find-replace
apple-bridge pages-insert-table
apple-bridge pages-list-sections
apple-bridge pages-export
apple-bridge pages-info
apple-bridge keynote-search
apple-bridge keynote-read
apple-bridge keynote-create
apple-bridge keynote-add-slide
apple-bridge keynote-edit-slide
apple-bridge keynote-remove-slide
apple-bridge keynote-reorder-slides
apple-bridge keynote-list-slides
apple-bridge keynote-list-themes
apple-bridge keynote-export
apple-bridge keynote-info
apple-bridge notes-folders
apple-bridge notes-list
apple-bridge notes-search
apple-bridge notes-read
apple-bridge contacts-groups
apple-bridge contacts-search
apple-bridge contacts-read

Environment Variables

• APPLE_BRIDGE_BIN - Override path to the Swift binary
• APPLE_BRIDGE_APP - Override path to the AppleBridge .app bundle

License

MIT