karlhepler/apple-mcp

Apple MCP Server

A Model Context Protocol (MCP) server that provides full read/write access to Apple Notes and Reminders apps on macOS. This server uses AppleScript as the backend to interact with these applications, providing a clean JSON API that Claude Desktop can use.

Features

Apple Notes Tools

• searchNotes - Search notes by content or title
• readNote - Get full note content using Core Data ID
• createNote - Create new notes with optional folder
• updateNote - Update existing notes (title, content, folder) - also moves notes between folders
• deleteNote - Remove notes
• listNotes - List notes with optional folder filtering
• listNoteFolders - Get all available note folders
• createNoteFolder - Create a new folder for organizing notes
• updateNoteFolder - Rename an existing folder
• deleteNoteFolder - Delete an empty folder (fails if folder contains notes)

Apple Reminders Tools

• searchReminders - Search reminders by content or title
• listReminders - List reminders with filters (list, completed, due dates)
• createReminder - Create new reminders with optional due date and list
• updateReminder - Update reminder properties
• completeReminder - Mark reminders as completed
• deleteReminder - Remove reminders
• listReminderLists - Get all available reminder lists
• createReminderList - Create a new list for organizing reminders
• updateReminderList - Rename an existing list
• deleteReminderList - Delete an empty list (fails if list contains reminders)

Prerequisites

• macOS (required for AppleScript)
• Node.js v18.0.0 or higher
• Claude Desktop application

Installation

1. Clone this repository:

git clone https://github.com/karlhepler/apple-mcp.git
cd apple-mcp

2. Install dependencies:

npm install

3. Build the TypeScript code:

npm run build

Configuration for Claude Desktop

1. Open Claude Desktop settings
2. Navigate to the MCP servers section
3. Add a new server with the following configuration:

{
  "apple-mcp": {
    "command": "node",
    "args": ["/path/to/apple-mcp/dist/index.js"],
    "env": {
      "APPLE_MCP_TIMEOUT": "60000",
      "APPLE_MCP_REMINDERS_TIMEOUT": "90000",
      "APPLE_MCP_DEBUG": "false"
    }
  }
}

Replace /path/to/apple-mcp with the actual path to this repository on your system.

Environment Variables (Optional)

• APPLE_MCP_TIMEOUT - Global timeout in milliseconds (default: 60000)
• APPLE_MCP_REMINDERS_TIMEOUT - Reminders-specific timeout (default: 60000)
• APPLE_MCP_NOTES_TIMEOUT - Notes-specific timeout (default: 30000)
• APPLE_MCP_RETRY_COUNT - Maximum retry attempts for timeouts (default: 2)
• APPLE_MCP_RETRY_DELAY - Initial retry delay in milliseconds (default: 1000)
• APPLE_MCP_DEBUG - Enable debug logging (default: false)

Permissions

The first time you use this MCP server, macOS will prompt you to grant permissions:

1. Automation Permission: Allow your terminal/Claude to control Notes and Reminders
2. Privacy Settings: Grant access in System Settings > Privacy & Security > Automation

If you encounter permission errors, check:

• System Settings > Privacy & Security > Automation
• Ensure your terminal app has permission to control Notes and Reminders

Usage Examples

Notes Operations

Search for notes:

{
  "tool": "searchNotes",
  "arguments": {
    "query": "meeting notes"
  }
}

Read a specific note:

{
  "tool": "readNote",
  "arguments": {
    "id": "x-coredata://1234/ICNote/p567"
  }
}

Create a new note:

{
  "tool": "createNote",
  "arguments": {
    "title": "Shopping List",
    "content": "- Milk\n- Eggs\n- Bread",
    "folder": "Personal"
  }
}

Update a note:

{
  "tool": "updateNote",
  "arguments": {
    "id": "x-coredata://1234/ICNote/p567",
    "title": "Updated Title",
    "content": "New content here"
  }
}

Move a note to a different folder:

{
  "tool": "updateNote",
  "arguments": {
    "id": "x-coredata://1234/ICNote/p567",
    "folder": "Work"
  }
}

Create a new folder:

{
  "tool": "createNoteFolder",
  "arguments": {
    "name": "Project Ideas"
  }
}

Rename a folder:

{
  "tool": "updateNoteFolder",
  "arguments": {
    "currentName": "Project Ideas",
    "newName": "Active Projects"
  }
}

Delete an empty folder:

{
  "tool": "deleteNoteFolder",
  "arguments": {
    "name": "Old Projects"
  }
}

Reminders Operations

Create a reminder with due date:

{
  "tool": "createReminder",
  "arguments": {
    "title": "Call dentist",
    "notes": "Schedule annual checkup",
    "due": "2024-12-30",
    "list": "Personal"
  }
}

List incomplete reminders:

{
  "tool": "listReminders",
  "arguments": {
    "completed": false,
    "list": "Work"
  }
}

Complete a reminder:

{
  "tool": "completeReminder",
  "arguments": {
    "id": "x-coredata://1234/REMCDReminder/p890"
  }
}

Technical Details

Architecture

• Frontend: MCP server (TypeScript/Node.js) exposing JSON APIs
• Backend: AppleScript files for Apple app interactions
• Communication: MCP server executes AppleScript and parses results
• Transport: StdioServerTransport for Claude Desktop compatibility

Data Handling

• Uses Core Data IDs (e.g., x-coredata://...) for consistent item references
• Dates are converted between ISO 8601 and AppleScript formats
• Rich text/HTML content in Notes is preserved
• Full PATCH-style updates (only specified fields are modified)

Error Handling

• Permission denied errors with helpful messages
• Item not found errors
• AppleScript execution failures
• Input validation using Zod schemas

Development

Project Structure

apple-mcp/
├── src/
│   ├── index.ts                 # Main MCP server
│   ├── types.ts                 # TypeScript interfaces
│   ├── tools/
│   │   ├── notes.ts            # Notes MCP tools
│   │   └── reminders.ts        # Reminders MCP tools
│   ├── applescript/
│   │   ├── executor.ts         # AppleScript wrapper
│   │   ├── notes/              # Notes AppleScripts
│   │   └── reminders/          # Reminders AppleScripts
│   └── utils/
│       ├── error-handler.ts
│       ├── date-formatter.ts
│       └── validators.ts

Development Commands

npm run dev        # Watch mode for development
npm run build      # Build TypeScript
npm run clean      # Clean build artifacts
npm run lint       # Run ESLint
npm run typecheck  # Type checking without emit
npm test           # Run comprehensive test suite
npm run quick-test # Run a quick functionality test

Code Quality

Before committing changes:

1. Run npm run lint to check code style
2. Run npm run typecheck to verify TypeScript types
3. Run npm test to ensure all tests pass (100% required)

Troubleshooting

Permission Denied

If you get permission denied errors:

1. Open System Settings > Privacy & Security > Automation
2. Find your terminal app or Claude Desktop
3. Enable access to Notes and Reminders

AppleScript Errors

• Ensure Notes/Reminders apps are installed and not corrupted
• Try running a simple AppleScript manually to test access
• Check Console.app for detailed error messages

Items Not Found

• Core Data IDs change if items are moved between devices
• Use search functions to find items by content if IDs fail
• Syncing issues may cause temporary inconsistencies

Testing

Quick Test

For a quick functionality check without running the full test suite:

npm run quick-test

This runs a basic test that:

• Lists note folders
• Creates, reads, updates, and deletes a test note
• Searches for notes
• Lists reminder lists
• Cleans up after itself

Full Test Suite

Run the comprehensive automated test suite to verify all functionality:

npm test

The test suite features:

• 100% coverage of all 14 documented tools (7 for Notes, 7 for Reminders)
• 45 automated tests with detailed validation
• Proper data verification - not just success flags
• Edge case testing including error handling
• Automatic cleanup of all test data
• Detailed reporting by feature category

Test Categories:

• Notes - Folders: Create, update, delete, and list folder operations
• Notes - CRUD: Full note lifecycle including creation, reading, updating, and deletion
• Notes - Search/List: Search by title/content and list with filtering
• Reminders - Lists: Create, update, delete, and list operations
• Reminders - Basic: Validates Reminders app connectivity
• Edge Cases: Error handling and boundary conditions

Notes:

• You may be prompted to grant automation permissions on first run
• Reminders tests are simplified to avoid timeout issues
• Tests account for Apple Notes behavior (e.g., Recently Deleted folder)

Known Limitations

1. Rich Text: Notes HTML content may have formatting limitations
2. Attachments: Image and file attachments in notes are not fully supported
3. Performance: Large numbers of notes/reminders may be slow to process
4. Sync: Changes may take time to sync across devices
5. Recurring Reminders: Limited support for complex recurrence rules
6. Search Indexing: Apple Notes search may have delays after creating/updating notes
7. Folder Assignment: Notes may not immediately reflect folder changes in read operations
8. Deletion Behavior: Deleted notes move to "Recently Deleted" rather than permanent deletion
9. Reminders Timeouts: Complex Reminders operations may timeout with large datasets

For a comprehensive list of Apple-specific behaviors and workarounds, see .

Security Considerations

• This server requires automation permissions which could be misused
• AppleScript has full access to Notes and Reminders content
• No authentication is built into the MCP protocol
• Use only on trusted systems with trusted clients

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Submit a pull request

License

MIT License - see LICENSE file for details

Support

For issues and questions:

• Check existing GitHub issues
• Create a new issue with detailed information
• Include macOS version and error messages