Content
# RemindersMCP
An MCP server that gives Claude (and any MCP client) full access to Apple Reminders via [`remindctl`](https://github.com/steipete/remindctl).
## What it does
10 tools, all returning JSON:
| Tool | Description |
|---|---|
| `show_reminders` | Filter by `today` / `tomorrow` / `week` / `overdue` / `upcoming` / `open` / `completed` / `all` / `YYYY-MM-DD` |
| `list_reminder_lists` | List all your reminder lists |
| `get_list_contents` | Show reminders in a specific list |
| `search_reminders` | Full-text search across titles, notes, and URLs |
| `get_reminder_info` | Full details for one reminder by index or ID prefix |
| `add_reminder` | Create with due date, alarm, notes, URL, priority, repeat |
| `edit_reminder` | Edit any field on an existing reminder |
| `complete_reminders` | Check off one or many |
| `delete_reminders` | Delete one or many |
| `create_list` | Create a new reminder list |
## Requirements
- macOS
- [remindctl](https://github.com/steipete/remindctl) — `brew install steipete/tap/remindctl`
- Python 3.12+
- `mcp` Python package — `pip3 install mcp`
## Setup
**1. Install dependencies**
```bash
brew install steipete/tap/remindctl
pip3 install mcp
```
**2. Grant Reminders access**
```bash
remindctl authorize
```
**3. Clone this repo**
```bash
git clone https://github.com/YOUR_USERNAME/RemindersMCP.git ~/RemindersMCP
```
**4. Add to Claude desktop config**
Edit `~/Library/Application Support/Claude/claude_desktop_config.json` and add:
```json
{
"mcpServers": {
"RemindersMCP": {
"command": "python3",
"args": ["/Users/YOUR_USERNAME/RemindersMCP/server.py"]
}
}
}
```
**5. Restart Claude desktop**
The 10 tools will appear automatically.
## Usage examples
Once connected, you can ask Claude things like:
- *"What do I have due today?"*
- *"Add a reminder to call mom tomorrow at 9am with high priority"*
- *"Search my reminders for anything about the dentist"*
- *"Mark reminder 3 as complete"*
- *"Move the 'Review docs' reminder to my Work list and set it due Friday"*
## How it works
Each tool shells out to `remindctl` with `--json --no-input` flags so all output is machine-readable. The server runs over stdio (standard MCP transport), so no port or daemon is needed.
## License
MIT
