# Apple Reminders MCP 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

```bash
# 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`):

```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:
> ```json
> {
>   "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:

```bash
# 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

```bash
# 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