# reminders-mcp

An MCP (Model Context Protocol) server for managing Apple Reminders via the [`remindctl`](https://github.com/steipete/remindctl) CLI on macOS. It is intended for **Claude Desktop** and **Claude CoWork**, which run sandboxed and cannot run remindctl directly; this server runs as a separate process and talks to remindctl for you.

## Prerequisites

- **macOS** (Apple Reminders framework required)
- **Node.js** >= 18
- **remindctl** — install via Homebrew:
  ```bash
  brew install steipete/tap/remindctl
  ```
- On first run, grant Reminders access when macOS prompts. Check status with `remindctl status`, request access with `remindctl authorize`, or enable manually in **System Settings > Privacy & Security > Reminders**.

## Tools

| Tool | Description |
|---|---|
| `status` | Check Apple Reminders authorization status |
| `show-reminders` | View reminders by filter (today, tomorrow, week, overdue, upcoming, completed, all, or YYYY-MM-DD date) and optional list name |
| `list-lists` | List all reminder lists with counts |
| `create-list` | Create a new reminder list |
| `rename-list` | Rename an existing list |
| `delete-list` | Delete a list and all its reminders |
| `add-reminder` | Create a reminder with optional list, due date, notes, and priority |
| `edit-reminder` | Modify a reminder's title, list, due date, notes, priority, or completion status |
| `complete-reminders` | Mark one or more reminders as completed |
| `delete-reminders` | Delete one or more reminders |

## Installation

```bash
npm install -g reminders-mcp
```

## Configuration

Edit `claude_desktop_config.json` (macOS):

- **Path**: `~/Library/Application Support/Claude/claude_desktop_config.json`

Add the MCP server (macOS only; the app uses Apple Reminders):

```json
{
  "mcpServers": {
    "reminders-mcp": {
      "command": "reminders-mcp",
      "args": []
    }
  }
}
```

Restart Claude Desktop or CoWork. The reminders tools (e.g. `status`, `show-reminders`) should appear in the tool list.

## Development

```bash
git clone https://github.com/mikakoivisto/reminders-mcp.git
cd reminders-mcp
npm install
npm run build
```

Run in watch mode during development:

```bash
npm run dev
```

Test the server directly (newline-separated JSON-RPC messages):

```bash
printf '%s\n%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' | node dist/index.js
```

## License

MIT