# Notes & Reminders MCP

A self-hosted MCP server that lets an AI assistant save notes and reminders directly into your own apps.
Say "remind me to call mom tomorrow at 6pm" or "note this down" in Claude, and the item is created in
Todoist or Notion.

Run it on a Raspberry Pi, home server or VPS. It works with Claude (web, mobile, desktop) and any MCP client.

## Supported apps

| App | Type | Needs |
|---|---|---|
| Todoist | Reminders | API token |
| Notion | Notes | Integration token |

Set up only the apps you use. Each app turns on automatically once its token is configured.

## How it works

```
Claude (web/mobile/desktop) -> HTTPS -> Tailscale Funnel -> your server :8787 -> app APIs
```

- Due dates like "tomorrow at 6pm" or "every Monday 9am" are passed to Todoist, which understands them.
- Requests for Apple Notes or Apple Reminders save nothing; the assistant asks which connected app to use instead.

## Requirements

- Node.js 20 or newer
- A machine that stays on (a Raspberry Pi 3, 4, 5 or Zero 2 W with 64-bit Raspberry Pi OS works well)
- A free Tailscale account, or a domain on Cloudflare, to make the server reachable

## Setup

### 1. Install

```bash
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs git
git clone https://github.com/<you>/notes-reminders-mcp.git
cd notes-reminders-mcp
npm ci && npm run build
```

### 2. Configure

```bash
cp .env.example .env
cp config.example.json config.json
npm run gen-secret        # paste the output into MCP_SECRET in .env
```

Edit `config.json`:

| Key | Description |
|---|---|
| `timezone` | Your IANA time zone, for example `Asia/Kathmandu` or `Europe/London` |
| `defaults.reminders` / `defaults.notes` | App used when none is named (`todoist`, `notion`) |
| `appleFallback.mode` | `ask` (assistant asks which app to use) or `default` (uses the apps set in `appleFallback`) |

### 3. Connect your apps

**Todoist**
1. Todoist > Settings > Integrations > Developer: copy the API token into `TODOIST_API_TOKEN` in `.env`.
2. Todoist > Settings > General: set your time zone.
3. Optional: set `todoist.defaultProject` in `config.json` (empty means Inbox).

**Notion**
1. Create an internal integration at https://www.notion.so/profile/integrations and copy the secret into `NOTION_TOKEN`.
2. Create a page for new notes, open its `...` menu > Connections, and add your integration.
3. Put the page ID (last 32 characters of the page URL) in `notion.parentPageId` in `config.json`.

Test the server:

```bash
npm start
curl http://127.0.0.1:8787/health     # in a second terminal, should return "ok":true
```

### 4. Run as a service

```bash
sudo cp deploy/notes-mcp.service /etc/systemd/system/
sudo nano /etc/systemd/system/notes-mcp.service    # replace "pi" with your username in all 4 places
sudo systemctl daemon-reload
sudo systemctl enable --now notes-mcp
```

View logs with `journalctl -u notes-mcp -f`.

### 5. Make it reachable

Using Tailscale Funnel (free, no domain needed):

```bash
curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up                  # open the link and approve the device
sudo tailscale funnel --bg 8787
```

The first time, follow the printed link to enable HTTPS and Funnel, then run the last command again.
It prints your address, for example `https://raspberrypi.tail1234.ts.net`. Open `/health` on that address from
another network to confirm it works. A new address can take a few minutes to become reachable.

Alternative: Cloudflare Tunnel with your own domain. See `deploy/cloudflared-config.example.yml`.

### 6. Connect Claude

In claude.ai, open Settings > Connectors > Add custom connector and enter:

```
https://<your-address>/mcp/<MCP_SECRET>
```

This works on the web, mobile and desktop apps. Allow the tools when Claude first asks.

Other MCP clients can use `https://<your-address>/mcp` with the header `Authorization: Bearer <MCP_SECRET>`.
To use Claude Desktop on the same machine without a tunnel, run the server with `node dist/server.js --stdio`.

Optional: add this to your Claude preferences so items are saved without asking:
"When I ask to be reminded of something or to note something down, save it with the Notes & Reminders tools."

## Usage

| Tool | Purpose |
|---|---|
| `create_reminder` | Create a task with optional due time, repeat, project and priority |
| `list_reminders` | Show upcoming tasks or filter them (Todoist filters like `today` or `#Work`) |
| `complete_reminder` | Mark a task as done |
| `create_note` | Save a note, optionally under a named page |
| `search_notes` | Find existing notes |
| `list_apps` | Show connected apps, projects and the current time |

Example prompts:

- "Remind me every Monday at 9am to water the plants"
- "Add pay rent to my Personal project on Nov 1 at 10am, urgent"
- "Note this down: trip ideas for Pokhara"
- "What is on my to-do list today?"

A successful save always replies with "Reminder created in ..." or "Note saved in ...".

## Updating

```bash
git pull && npm ci && npm run build && sudo systemctl restart notes-mcp
```

Your `.env` and `config.json` are kept.

## Security

- The connector URL contains your secret. Keep it private, and change `MCP_SECRET` if it leaks.
- The server listens only on `127.0.0.1` and rejects requests without the secret.
- `.env` and `config.json` are excluded from Git. Never commit them.

## Troubleshooting

| Problem | Fix |
|---|---|
| Address not reachable | Run `tailscale funnel status`; it must show "Funnel on". Wait a few minutes for DNS. |
| Claude replies but nothing is saved | Ask it to "save it", or add the preference text above |
| Wrong due time | Check the time zone in Todoist and `timezone` in `config.json` |
| Project not found | Ask "which apps are connected?" to see the exact names |
| Notion page not found | Share the page with your integration (`...` > Connections) |

## Development

```bash
node test/mock-apis.mjs     # fake Todoist and Notion APIs on port 9911
```

Run the server with `TODOIST_BASE_URL` and `NOTION_BASE_URL` set to `http://127.0.0.1:9911`, then run
`MCP_URL=http://127.0.0.1:8787/mcp/<secret> node test/smoke-all.mjs`.

To add an app, implement `RemindersProvider` or `NotesProvider` from `src/providers/types.ts` and register it in
`src/providers/index.ts`.

## Roadmap

- Microsoft To Do, OneNote, Obsidian, TickTick and Google Tasks
- Apple Notes and Apple Reminders through a separate Mac server
- Docker image

## License

MIT