MCP Apple Reminders
by rex
README.md
# MCP Apple Reminders
A macOS-only [Model Context Protocol](https://modelcontextprotocol.io) server that
exposes Apple Reminders to Claude Code, Codex, and the Claude Desktop app. It can
create, read, update, delete, search, and organize reminders and lists, drive a
Claude-* workflow board, manage sidebar groups, set alarms and recurrence, run bulk
operations, and work with subtasks, sections, and tags.
The server is built on MCP Python SDK 2.3 (`MCPServer`) and reads/writes Apple Reminders
through a three-tier native stack (direct SQLite reads + a Swift EventKit helper +
an Objective-C ReminderKit helper). See [Architecture](#architecture).
It serves modern discovery and legacy initialization. Bulk deletion requires
client elicitation; clients without sampling receive triage items and instructions
for classification in the calling assistant.
## Features
- **58 MCP tools** across 17 modules (full catalog in [`docs/TOOLS.md`](docs/TOOLS.md)).
- **Calendar/list management** — create, delete, update, search lists.
- **Reminder CRUD** — create, update, complete/uncomplete, delete, fetch by ID.
- **Rich queries** — today, overdue, next-up, completed-in-range, text search, filters.
- **Workflow board** — move reminders across Pierce's `Claude-*` lists.
- **Sidebar groups** — create/list/delete folders and move lists into them.
- **Alarms & recurrence** — time alarms, location alarms, repeat rules.
- **Bulk operations** — complete, move, and purge-completed in one call.
- **Subtasks, sections & tags** — hierarchy and grouping via the ReminderKit helper.
- **MCP Resources, Prompts, Elicitation, Sampling, and progress reporting** (see below).
- **Deeplinks** — every Reminder and Calendar carries an `x-apple-reminderkit://` deeplink.
## Requirements
- **OS**: macOS (EventKit-backed; macOS owns iCloud sync). No cross-platform support.
- **Python**: 3.10+ (the repo venv runs 3.13).
- **Xcode Command Line Tools**: `swiftc` + `clang`, required once to compile the native helpers.
- **Permission**: Reminders access, granted **per interpreter binary** (see [Permissions](#permissions)).
- **MCP client**: Claude Code, Codex, the Claude Desktop app, or any MCP-compatible client.
Key dependencies: MCP Python SDK `1.27.x` (FastMCP), Pydantic v2, and PyObjC/EventKit.
## Installation
### Recommended: `install.sh`
From the repo root:
```bash
./install.sh
```
This creates `./venv`, installs the package in editable mode with its dependencies,
and compiles the native helpers (`make build-native`).
### Manual
```bash
python3 -m venv venv
source venv/bin/activate
pip install -e ".[dev]"
make build-native # compiles the Swift + Obj-C helpers into _native/bin/
```
### Verify the install
```bash
./venv/bin/python3 -c "from mcp_apple_reminders import cli_main; print('ok')"
./venv/bin/python3 verify_setup.py # preflight: interpreter, deps, perms, client configs
```
`verify_setup.py` triggers the macOS Reminders permission prompt on first run. Approve it.
## Configuration
In every client, the launch command **must** be this repo's venv interpreter
(the binary that was granted Reminders access — see [Permissions](#permissions)),
not a bare `python3`. On many macOS systems `/usr/bin/python3` is too old anyway.
Replace `/absolute/path/to/mcp-apple-reminders` with your local checkout in each snippet.
### Claude Code
```bash
claude mcp add apple-reminders \
/absolute/path/to/mcp-apple-reminders/venv/bin/python3 -- -m mcp_apple_reminders
```
### Codex
Codex reads MCP servers from `~/.codex/config.toml`:
```toml
[mcp_servers.apple-reminders]
command = "/absolute/path/to/mcp-apple-reminders/venv/bin/python3"
args = ["-m", "mcp_apple_reminders"]
cwd = "/absolute/path/to/mcp-apple-reminders"
enabled = true
```
### Claude Desktop app
Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
```json
{
"mcpServers": {
"apple-reminders": {
"command": "/absolute/path/to/mcp-apple-reminders/venv/bin/python3",
"args": ["-m", "mcp_apple_reminders"],
"env": {}
}
}
}
```
Restart Claude Desktop, then look for the tools under "apple-reminders".
### First-run permission shim
If the Reminders permission prompt never appears, point the client's `command` at
`./shim_mcp.sh` (args `[]`) once to surface the prompt, then switch back to the venv
interpreter above.
### Other clients
The server speaks MCP over stdio. The general invocation is:
```bash
/absolute/path/to/mcp-apple-reminders/venv/bin/python3 -m mcp_apple_reminders
```
## Permissions
Apple Reminders access is granted **per binary**, so the exact interpreter the client
launches (the conda/venv `python3`) must be the one that holds the grant.
1. On first launch macOS shows a permission dialog — click **OK**.
2. If you miss it, run `./venv/bin/python3 verify_setup.py` (or `./shim_mcp.sh`) once and approve.
3. To inspect/toggle manually: **System Settings → Privacy & Security → Reminders**.
Without the grant the server cannot read or write reminders.
## Tools, Resources & Prompts
The 58 tools are grouped into 17 modules under `src/mcp_apple_reminders/tools/`.
The exhaustive, always-current catalog (parameters + return shapes) lives in
[`docs/TOOLS.md`](docs/TOOLS.md). Summary by category:
| Category | Count | What it does |
|---|---|---|
| **calendars** | 8 | create/delete/update lists, get by name/ID, default, list, search |
| **reminders** | 4 | create, update, delete, get by ID |
| **completion** | 2 | complete / uncomplete shortcuts |
| **queries** | 7 | get/filter, today, overdue, next-up, completed-in-range, search, recently-deleted |
| **workflow** | 6 | move across `Claude-*` board lists; list the board |
| **groups** | 4 | create/list/delete sidebar folders; move a list into a group |
| **alarms** | 3 | time alarm, location alarm, recurrence rule |
| **bulk** | 3 | bulk complete, bulk move, bulk delete-completed |
| **sections** | 3 | get subtasks, set parent, assign section |
| **smartlists** | 3 | create/update/delete custom smart lists |
| **appearance** | 3 | list/smart-list appearance + pinning |
| **templates** | 3 | create/apply/delete list templates |
| **flags** | 3 | set urgent, set early reminder, add section + assign |
| **attachments** | 3 | add URL / metadata / file attachments |
| **grocery** | 1 | `categorize_grocery_items` |
| **agents** | 1 | `bootstrap_agent_list` — agent-visibility plane |
| **sampling** | 1 | `triage_brain_dump` — server-initiated LLM sampling |
The **workflow board** is Pierce's `Claude-*` list family: `Claude-Brain-Dump`,
`Claude-On-Deck`, `Claude-Active`, `Claude-Waiting`, and `Claude-Done`. **Groups** are
Reminders.app sidebar folders.
Beyond tools, the server also exposes:
- **MCP Resources** (read-only views): `reminders://default`, `reminders://today`,
`reminders://overdue`, `reminders://list/{calendar_id}`, `reminders://recently-deleted`,
`reminders://tags`, `reminders://appearance`, and `agents://current/{project_name}`
(the agent-visibility plane).
- **MCP Prompts**: `daily_review`, `weekly_retro`, `brain_dump_triage`, `agent_visibility_sync`,
`organize_into_sections`.
- **Elicitation guards** on destructive operations (e.g. deletes/purges).
- **Server-initiated Sampling** via `triage_brain_dump`.
- **Progress reporting** on long-running operations.
## Usage examples
Once configured, ask your client in natural language — it picks the tools:
- "Show me everything due today." → `get_today_reminders`
- "Remind me to call the dentist tomorrow at 2pm." → `create_reminder`
- "What am I behind on?" → `get_overdue_reminders`
- "Move the 'update docs' task to Active." → `move_reminder_active`
- "Triage my brain dump." → `triage_brain_dump` (with elicitation/sampling)
## Architecture
`server.py` is the FastMCP instance; importing the `tools`, `resources`, and `prompts`
packages registers everything against it. `lifespan.py` builds the `AppContext`
(SQLite store path + helper binary paths); `models.py` holds frozen Pydantic v2 models,
each Reminder/Calendar carrying a `deeplink` (e.g. `x-apple-reminderkit://REMCDReminder/{uuid}`).
All native access lives under `src/mcp_apple_reminders/_native/` in three tiers:
1. **SQLite reads** (`sqlite.py`) — reads the Reminders.app CoreData SQLite store
directly. Fast path for reads, including sections, subtasks, tags, and groups.
2. **EventKit writes** (`eventkit.py`) — Python wrapper around a compiled Swift
EventKit helper subprocess for public-API writes. Binary `_native/bin/rem_eventkit`,
compiled from `_native/src/rem_eventkit.swift`.
3. **ReminderKit writes** (`reminderkit.py` transport + `reminderkit_actions.py` typed
wrappers) — Python wrapper around a compiled Objective-C ReminderKit (a **private**
framework) helper subprocess for subtasks, tags, sections, flagged state, and groups.
Binary `_native/bin/rem_reminderkit`, compiled from `_native/src/rem_reminderkit.m`.
Both native helpers are borrowed from [viticci/remctl](https://github.com/viticci/remctl)
(MIT); see [`src/mcp_apple_reminders/_native/THIRD_PARTY_NOTICES.md`](src/mcp_apple_reminders/_native/THIRD_PARTY_NOTICES.md).
```
Client (Claude Code / Codex / Claude Desktop)
| MCP over stdio (JSON-RPC)
server.py (FastMCP: tools + resources + prompts)
| lifespan AppContext (sqlite path, helper paths)
_native/ ── sqlite.py ........... direct CoreData SQLite reads
├ eventkit.py ........ Swift helper subprocess (public-API writes)
└ reminderkit.py ..... Obj-C helper subprocess (private-framework writes)
|
Apple Reminders store
```
**No stdout, ever.** stdio *is* the JSON-RPC transport; any stray `print` corrupts the
protocol. All logs go to stderr only.
## Development
```bash
# Lint, format-check, line-limit gate
ruff check src/ test_*.py test_support/
black --check src/ test_*.py test_support/
make check-architecture # hard cap 400 lines/file
# Tests (root-level, explicit paths — root is not on testpaths)
./venv/bin/python -m pytest test_mcp_tools.py test_workflow_tools.py test_e2e.py
# Rebuild native helpers after editing the Swift/Obj-C sources
make build-native # or: make clean-native && make build-native
```
Run the server directly for debugging (logs to stderr):
```bash
./venv/bin/python3 -m mcp_apple_reminders
```
The installed console script `mcp-apple-reminders` maps to `mcp_apple_reminders:cli_main`.
## Troubleshooting
- **"No access to reminders"** — the grant is per binary. Confirm the client launches
the venv interpreter and that *that* binary is enabled under System Settings →
Privacy & Security → Reminders. Re-run `verify_setup.py` or `./shim_mcp.sh` to re-prompt.
- **Tools missing in the client** — verify the config path and JSON/TOML syntax, confirm
the interpreter path is absolute, and fully restart the client.
- **`ModuleNotFoundError`** — reinstall: `pip install -e ".[dev]"`.
- **Native helper missing / write failures** — run `make build-native` (needs Xcode CLI
tools). Check `_native/bin/rem_eventkit` and `_native/bin/rem_reminderkit` exist.
- **DateTime errors** — use ISO 8601, e.g. `2026-01-15T14:30:00`.
- **Reminder not found** — the ID may be stale; re-fetch via `search_reminders` / `get_reminders`.
Client logs (Claude Desktop): `tail -f ~/Library/Logs/Claude/mcp*.log`.
## Further docs
- [`docs/TOOLS.md`](docs/TOOLS.md) — full tool catalog.
- [`docs/MAP.md`](docs/MAP.md) — module map.
- [`docs/SQLITE_SCHEMA.md`](docs/SQLITE_SCHEMA.md) — Reminders SQLite schema notes.
- [`docs/SECURITY-REVIEW.md`](docs/SECURITY-REVIEW.md) — security review.
- [`AGENTS.md`](AGENTS.md) — agent collaboration guide.
- [`CHANGELOG.md`](CHANGELOG.md) — release history.
## License
MIT. See [LICENSE](LICENSE). Native helpers are MIT-licensed third-party code — see
[`src/mcp_apple_reminders/_native/THIRD_PARTY_NOTICES.md`](src/mcp_apple_reminders/_native/THIRD_PARTY_NOTICES.md).
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues