Apple MCP

Apple MCP allows AI agents to interact with various Apple applications on your Mac. Supported capabilities include:

• Messages: Send, read, and schedule messages.
• Notes: Create, search, and retrieve notes.
• Contacts: Find contacts and retrieve phone numbers.
• Mail: Send emails (with attachments, CC, BCC), search emails, schedule emails, and check unread counts.
• Reminders: Create, search, list, and open reminders.
• Calendar: Create, search, list, and open calendar events.
• Maps: Search locations, save favorites, get directions, create guides, and drop pins.

Commands can be chained together (e.g., "Read my notes, find the contact, and send them a message").

The easiest way to install the Apple MCP server is using Smithery. Use the following commands depending on your AI client:

For Claude Desktop:

npx -y install-mcp apple-mcp --client claude

For Cursor:

npx -y install-mcp apple-mcp --client cursor

Because the tests interact with real Apple applications, you must grant the following permissions in System Preferences:

1. Contacts Access: Grant when prompted.
2. Calendar Access: Grant when prompted.
3. Reminders Access: Grant when prompted.
4. Notes Access: Grant when prompted.
5. Mail Access: Ensure Mail.app is configured.
6. Messages Access: May require Full Disk Access for your terminal emulator (e.g., Terminal.app or iTerm.app).
   • Path: System Preferences > Security & Privacy > Privacy > Full Disk Access

If you need more detailed output or want to run tests in development mode, use the following commands:

• Use npm run test:contacts-full for more verbose contacts testing.
• Use npm run test:watch to run tests in watch mode.

# More verbose contacts testing
npm run test:contacts-full

# Watch mode for development
npm run test:watch

To contribute to or test the Apple MCP project locally, follow these steps:

1. Clone the repository: git clone https://github.com/dhravya/apple-mcp.git
2. Navigate to the directory: cd apple-mcp
3. Install dependencies using Bun: bun install
4. Run the project: bun run index.ts

If you prefer manual installation, you must first ensure bun is installed on your system. Then, add the apple-mcp configuration to your claude_desktop_config.json file.

1. Install Bun (if not already installed):

brew install oven-sh/bun/bun

2. Update claude_desktop_config.json with the following entry:

{
  "mcpServers": {
    "apple-mcp": {
      "command": "bunx",
      "args": ["--no-cache", "apple-mcp@latest"]
    }
  }
}

You can run the full test suite or target specific tool integrations using npm scripts. The tests interact with real Apple apps via AppleScript/JXA and use a deterministic test phone number: +1 9999999999.

# Run all tests
npm run test

# Run specific tool tests
npm run test:contacts
npm run test:messages
npm run test:notes
npm run test:mail
npm run test:reminders
npm run test:calendar
npm run test:maps
npm run test:web-search
npm run test:mcp

Common issues encountered during testing:

• Permission Denied Errors: Ensure permissions are granted in System Preferences and restart your terminal after granting them.
• Timeout Errors: Apple apps may be slow to respond; ensure your system is not under heavy load.
• "Command failed" Errors: Usually indicates permission issues or that a required Apple app is not installed/accessible.
• JXA/AppleScript Errors: Ensure the relevant Apple app is not busy or in a restricted mode. Try closing and reopening the app.

The notes tool provides access to the macOS Notes application. It supports searching, listing, and creating new notes.

Operations:

• search: Find notes containing specific text. Requires searchText.
• list: Retrieve all existing notes.
• create: Create a new note. Requires title and body. Optionally accepts folderName.

The calendar tool manages events in the macOS Calendar app.

Operations:

• search: Search for events using searchText. Supports limit, fromDate, and toDate filters.
• open: Open a specific event in the Calendar app using eventId.
• list: List events within a date range. Supports limit, fromDate, and toDate.
• create: Create a new event. Requires title and startDate. Optionally accepts endDate, location, notes, isAllDay, and calendarName.

The mail tool interacts with the macOS Mail app to manage emails.

Operations:

• unread: Get unread emails. You can filter by account and mailbox. Supports a limit parameter.
• search: Search for emails using a searchTerm. Supports account and mailbox filters.
• send: Send an email. Requires to, subject, and body. Optionally accepts cc and bcc.
• mailboxes: List available mailboxes. Can be filtered by account.
• accounts: List all configured email accounts.
• latest: Retrieve the most recent emails from a specific account.