# RTM MCP Server

A production-quality [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) server for [Remember The Milk](https://www.rememberthemilk.com/) task management.

Enables Claude to manage your tasks through natural language conversation.

## Features

- **Full RTM API Coverage**: 30+ tools covering tasks, lists, tags, notes, and more
- **Smart Add Syntax**: Natural language task creation (`"Call mom ^tomorrow !1 #family"`)
- **Undo Support**: All write operations return transaction IDs for undo
- **Async Performance**: Built on httpx with connection pooling
- **Type Safety**: Full Pydantic models and type hints

## Installation

### Using uvx (Recommended)

```bash
uvx rtm-mcp
```

### Using pip

```bash
pip install rtm-mcp
```

### From Source

```bash
git clone https://github.com/ljadach/rtm-mcp.git
cd rtm-mcp
uv sync
```

## Setup

### 1. Get RTM API Credentials

RTM API keys are issued through a separate developer portal (not your account settings):

1. Go to [RTM API Key Registration](https://www.rememberthemilk.com/services/api/keys.rtm) — you may need to log in first
2. Click **"Apply for an API Key"**
3. Fill in the form — app name (e.g. "Claude MCP"), description, anything works
4. After submitting, you'll see your **API Key** and **Shared Secret** — save both

### 2. Run Setup

```bash
rtm-setup
```

This will:
- Prompt for your API credentials
- Open your browser for authorization
- Save the auth token to `~/.config/rtm-mcp/config.json`

### 3. Configure Claude Desktop

Add to `~/.config/claude/claude_desktop_config.json`:

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

## Usage

Once configured, you can ask Claude to manage your tasks:

- *"Show my tasks due today"*
- *"Add a task to buy groceries tomorrow, high priority"*
- *"Complete the grocery task"*
- *"What high priority tasks do I have?"*
- *"Move the meeting prep task to my Work list"*
- *"Add a note to the project task"*

## Smart Add Syntax

When adding tasks, use RTM's Smart Add syntax:

| Symbol | Meaning | Example |
|--------|---------|---------|
| `^` | Due date | `^tomorrow`, `^next friday` |
| `!` | Priority | `!1` (high), `!2` (medium), `!3` (low) |
| `#` | Tag | `#work`, `#urgent` |
| `@` | Location | `@home`, `@office` |
| `=` | Estimate | `=30min`, `=2h` |
| `*` | Repeat | `*daily`, `*every monday` |

Example: `"Review report ^friday !1 #work =1h *weekly"`

## Available Tools

### Tasks
- `list_tasks` - List tasks with filters
- `add_task` - Create a new task
- `complete_task` / `uncomplete_task` - Mark done or reopen
- `delete_task` - Remove a task
- `postpone_task` - Move due date by one day
- `move_task` - Move to different list
- `set_task_name` - Rename task
- `set_task_due_date` - Change due date
- `set_task_priority` - Set priority level
- `set_task_recurrence` - Set repeat pattern
- `set_task_start_date` - Set start date
- `set_task_estimate` - Set time estimate
- `set_task_url` - Attach URL
- `add_task_tags` / `remove_task_tags` - Manage tags

### Notes
- `add_note` - Add note to task
- `edit_note` - Edit existing note
- `delete_note` - Remove note
- `get_task_notes` - View all notes

### Lists
- `get_lists` - List all lists
- `add_list` - Create new list
- `rename_list` - Rename list
- `delete_list` - Delete list
- `archive_list` / `unarchive_list` - Archive management
- `set_default_list` - Set default list

### Utilities
- `test_connection` - Test API connectivity
- `check_auth` - Verify authentication
- `get_tags` - List all tags
- `get_locations` - List saved locations
- `get_settings` - View user settings
- `get_contacts` / `get_groups` - Contact management
- `parse_time` - Parse natural language time
- `undo` - Undo previous operation

## Configuration

### Environment Variables

```bash
RTM_API_KEY=your_api_key
RTM_SHARED_SECRET=your_shared_secret
RTM_AUTH_TOKEN=your_token
```

### Config File

`~/.config/rtm-mcp/config.json`:
```json
{
  "api_key": "your_api_key",
  "shared_secret": "your_shared_secret",
  "token": "your_token"
}
```

## Development

```bash
# Install dev dependencies
make dev

# Run linting
make lint

# Run tests
make test

# Run with coverage
make test/coverage

# Format code
make format
```

## Docker

```bash
docker build -t rtm-mcp .
docker run -it --rm \
  -e RTM_API_KEY \
  -e RTM_SHARED_SECRET \
  -e RTM_AUTH_TOKEN \
  rtm-mcp
```

Claude Desktop config for Docker:
```json
{
  "mcpServers": {
    "rtm": {
      "command": "docker",
      "args": ["run", "-i", "--rm",
        "-e", "RTM_API_KEY",
        "-e", "RTM_SHARED_SECRET",
        "-e", "RTM_AUTH_TOKEN",
        "rtm-mcp"]
    }
  }
}
```

## License

MIT License - see [LICENSE](LICENSE) for details.

## Acknowledgments

- [Remember The Milk](https://www.rememberthemilk.com/) for the excellent task management service
- [FastMCP](https://github.com/jlowin/fastmcp) for the MCP framework
- [Anthropic](https://anthropic.com/) for Claude and the MCP specification