Apple Reminders Server

A Model Context Protocol (MCP) server that allows AI assistants to interact with Apple Reminders on macOS using AppleScript.

Requirements

• macOS (required for AppleScript/Reminders integration)
• Node.js 18+
• Apple Reminders app with at least one list
• Automation permission (automatic prompt on first run)

Installation

# Clone the repository
git clone https://github.com/leawn/apple_reminders_mcp.git
cd apple_reminders_mcp

# Install dependencies and build
npm install

Usage with Cursor

Add to your Cursor MCP settings (~/.cursor/mcp.json):

{
  "mcpServers": {
    "apple-reminders": {
      "command": "/path/to/node",
      "args": ["/path/to/apple_reminders_mcp/dist/index.js"]
    }
  }
}

Important: Use the full path to node, not just node. Find it with which node.

Example for nvm users:

{
  "mcpServers": {
    "apple-reminders": {
      "command": "/Users/yourname/.nvm/versions/node/v20.16.0/bin/node",
      "args": ["/Users/yourname/path/to/apple_reminders_mcp/dist/index.js"]
    }
  }
}

Available Tools

Tool	Description	Parameters
listReminderLists	Get all reminder lists	-
getReminders	Get reminders from a list	listName, includeCompleted?
createReminder	Create a new reminder	listName, title, notes?, dueDate?, priority?
completeReminder	Mark reminder as done	listName, reminderId
uncompleteReminder	Mark reminder as incomplete	listName, reminderId
deleteReminder	Delete a reminder	listName, reminderId
updateReminder	Update reminder details	listName, reminderId, title?, notes?, dueDate?, priority?

Tool Parameters

Priority Values

• 0 - No priority
• 1 - High priority
• 5 - Medium priority
• 9 - Low priority

Date Format

Dates should be in ISO8601 format:

2024-12-31T09:00:00Z
2024-12-31T09:00:00-05:00

CLI Reference

The shell script can be used directly for testing:

# List all reminder lists
./bin/reminders-helper.sh list-lists

# Get reminders from a list
./bin/reminders-helper.sh get-reminders --list "Work"
./bin/reminders-helper.sh get-reminders --list "Work" --include-completed

# Create a reminder
./bin/reminders-helper.sh create --list "Work" --title "New task"
./bin/reminders-helper.sh create --list "Work" --title "Meeting" --notes "Team sync" --due "2024-12-31T09:00:00Z" --priority 1

# Complete a reminder
./bin/reminders-helper.sh complete --list "Work" --id "x-apple-reminder://UUID"

# Uncomplete a reminder
./bin/reminders-helper.sh uncomplete --list "Work" --id "x-apple-reminder://UUID"

# Update a reminder
./bin/reminders-helper.sh update --list "Work" --id "x-apple-reminder://UUID" --title "Updated title"

# Delete a reminder
./bin/reminders-helper.sh delete --list "Work" --id "x-apple-reminder://UUID"

Permissions

On first run, macOS will prompt you to grant Automation permission for controlling the Reminders app. This uses the standard Automation permission (not the Reminders privacy permission), which is easier to grant and manage.

If you see permission errors:

1. Open System Settings → Privacy & Security → Automation
2. Find Terminal/Cursor and enable "Reminders"

Development

# Run TypeScript directly (without building)
npm run dev

# Build TypeScript
npm run build

# Start the server
npm start

Troubleshooting

"Not authorized to send Apple events"

1. Open System Settings → Privacy & Security → Automation
2. Find the app running the MCP server (Terminal, Cursor, etc.)
3. Enable "Reminders" permission
4. Restart the MCP server

"List 'X' not found"

Make sure the list name matches exactly (case-sensitive). Use listReminderLists to see available lists.

Commands are slow

The helper uses AppleScript with bulk property access, which should be fast. If commands are slow:

• Check if Reminders.app is responding
• Try quitting and reopening Reminders.app
• Restart the MCP server

License

MIT