# reminders-mcp

An MCP server that reads and changes the local Apple Reminders on this Mac. It
copies the structure of `cal-mcp`, and it uses EventKit through PyObjC.

- Transport: streamable HTTP at `http://127.0.0.1:8002/mcp`
- Port 8002 keeps it clear of other local MCP servers on 8000 and 8001
- The server writes. It creates, changes, and deletes reminders.

## Tools

| Tool | Purpose |
| --- | --- |
| `ping` | Test the connection. |
| `list_reminder_lists` | Show every list, its account, and the default list. |
| `get_reminders` | Read reminders. Filter by list, due date, text, or completion. |
| `create_reminder` | Add one reminder, with a due date, notes, and priority. |
| `update_reminder` | Change the title, due date, notes, priority, list, or state. |
| `complete_reminder` | Mark one reminder done, or reopen it. |
| `delete_reminder` | Delete one reminder. This cannot be undone. |

Every tool except `create_reminder` and the two list tools needs the `id` that
`get_reminders` returns.

## Two lists can share a title

Two accounts can each hold a list named `Tasks`, for example a work account and
a personal account. A write tool refuses an ambiguous title and names the
choices. Send the account too, in the form `Work/Tasks`.

## Install

    python3 -m venv .venv
    .venv/bin/pip install -r requirements.txt

## Run

    .venv/bin/python server.py

The launchd agent starts it at login and restarts it on failure. The file holds
the placeholder `/Users/YOUR-USER`, so replace it with your own home folder:

    cp com.burghr.reminders-mcp.plist ~/Library/LaunchAgents/
    sed -i '' "s|/Users/YOUR-USER|$HOME|g" ~/Library/LaunchAgents/com.burghr.reminders-mcp.plist
    launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.burghr.reminders-mcp.plist

The log goes to `~/Library/Logs/reminders-mcp.log`.

## Access

macOS binds the Reminders grant to the program that starts the server, not to
`server.py`. A start from a different program raises a new prompt. Open System
Settings, then Privacy & Security, then Reminders, to see or change the grant.

## Read-only mode

Set `REMINDERS_READONLY=1` in the environment to refuse every write. The read
tools keep working.