RTM MCP Server

A Model Context Protocol (MCP) server for Remember The Milk that provides comprehensive task management functionality through Claude Desktop.

Important consideration before using this code or interacting with this codebase

This application is an experiment in using Claude Code as the primary driver the development of a small, focused app that concerns itself with the owner's particular point of view on the task it is accomplishing.

As such, this is not meant to be what people think of as "an open source project," because I don't have a commitment to building a community around it and don't have the bandwidth to maintain it beyond "fix bugs I find in the process of pushing it in a direction that works for me."

It's important to understand this for a few reasons:

If you use this code, you'll be using something largely written by an LLM with all the things we know this entails in 2025: Potential inefficiency, security risks, and the risk of data loss.
If you use this code, you'll be using something that works for me the way I would like it to work. If it doesn't do what you want it to do, or if it fails in some way particular to your preferred environment, tools, or use cases, your best option is to take advantage of its very liberal license and fork it.
I'll make a best effort to only tag the codebase when it is in a working state with no bugs that functional testing has revealed.

While I appreciate and applaud assorted efforts to certify code and projects AI-free, I think it's also helpful to post commentary like this up front: Yes, this was largely written by an LLM so treat it accordingly. Don't think of it like code you can engage with, think of it like someone's take on how to do a task or solve a problem.

Overview

This MCP server enables Claude to interact with Remember The Milk tasks, lists, and metadata using natural language. It implements most RTM API functionality with user-friendly responses and proper error handling.

This is the Python implementation of the RTM MCP Server, ported from the original Ruby version with complete feature parity and comprehensive test coverage.

Original Ruby Version: This project was ported from mph-llm-experiments/rtm-mcp (the original Ruby implementation). The Python version maintains 100% feature parity with the original.

Features

✅ Fully Implemented

Core Functionality

Connection Testing: Verify API connectivity and auth status
List Management: Create, list, and archive RTM lists
Task CRUD: Create, read, update, delete tasks with full metadata support

Task Operations

Task Creation: Create tasks in specific lists with natural language parsing
Task Completion: Mark tasks complete (handles recurring tasks properly)
Task Deletion: Permanently delete tasks (stops recurrence)
Task Moving: Move tasks between lists
Task Postponing: Postpone due dates

Task Metadata

Priorities: Set high (1), medium (2), low (3), or no priority
Due Dates: Set/clear due dates with natural language ("tomorrow", "next Friday", etc.)
Start Dates: Set/clear start dates with natural language parsing
Time Estimates: Set/clear time estimates ("30 minutes", "2 hours", etc.)
Tags: Add and remove tags from tasks
Task Names: Rename tasks
Notes: Add, edit, delete, and read task notes
Locations: Set/clear locations from predefined RTM locations with 📍 display
URLs: Set/clear task URLs with 🌐 display
Permalinks: Generate RTM web interface links for tasks

Advanced Features

Recurrence: Set and clear recurring task patterns
Subtasks: Create and list subtasks (requires RTM Pro)
Search & Filtering: List tasks with various filters and search criteria
Location Management: List predefined locations and set task locations
Bulk Operations: Move tasks between lists, batch tag operations

⚠️ Known Limitations

Subtasks

Create Subtask: ✅ Works (requires RTM Pro account)
List Subtasks: ⚠️ Workaround implementation (RTM API limitation)

Implementation Status

The RTM MCP server now implements comprehensive RTM functionality including:

✅ All core task operations (CRUD, metadata, search)
✅ Location support with predefined location management
✅ URL and permalink functionality
✅ Advanced features (recurrence, subtasks, bulk operations)
✅ Comprehensive error handling and user-friendly responses

The server provides nearly complete coverage of RTM's API functionality suitable for daily task management through Claude Desktop.

Quick Setup

# 1. Get RTM API credentials from https://www.rememberthemilk.com/services/api/keys.rtm

# 2. Create .env file with credentials
cp .env.example .env
# Edit .env with your RTM_API_KEY and RTM_SHARED_SECRET

# 3. (Optional) Get auth token via OAuth for authenticated operations
# See "Getting Your Auth Token" section below

# 4. Install Python dependencies
uv pip install -e .

# 5. Add to Claude Desktop config
# See detailed instructions below

Installation & Setup

1. Get RTM API Credentials

Visit https://www.rememberthemilk.com/services/api/keys.rtm
Request an API key and shared secret
Note your API key and shared secret

2. Set Up Credentials (.env file)

Create a .env file in the project root with your credentials:

# Copy the example and edit with your actual credentials
cp .env.example .env

Edit .env:

RTM_API_KEY=your_rtm_api_key_here
RTM_SHARED_SECRET=your_rtm_shared_secret_here
RTM_AUTH_TOKEN=your_rtm_auth_token_here  # Optional - for authenticated operations

About RTM_AUTH_TOKEN:

Optional but recommended for full functionality
Some read operations work with just API key + secret
Write operations (create, update, delete) require auth token
Get token from RTM OAuth flow (see "Getting Your Auth Token" section)

3. Install Python Dependencies

# Using uv (recommended, faster)
uv pip install -e .

# Or using pip
pip install -e .

4. (Optional) Run Tests

# Run all tests
pytest tests/ -v

# Run only unit tests (no API needed)
pytest tests/test_unit.py -v

# Run integration tests with your RTM credentials
pytest tests/test_integration.py -v -s

5. Configure Claude Desktop

Add to your Claude Desktop MCP settings (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "rtm-mcp": {
      "command": "python",
      "args": ["-m", "rtm_mcp"],
      "env": {
        "RTM_API_KEY": "your_api_key_here",
        "RTM_SHARED_SECRET": "your_shared_secret_here",
        "RTM_AUTH_TOKEN": "your_auth_token_here"
      }
    }
  }
}

Or, alternatively use environment variables from .env by running with python rtm_mcp.py:

{
  "mcpServers": {
    "rtm-mcp": {
      "command": "python",
      "args": ["/path/to/rtm_mcp.py"]
    }
  }
}

6. (Optional) Getting Your Auth Token

For full access to write operations (create, update, delete tasks), you'll need an auth token:

Visit: https://www.rememberthemilk.com/services/oauth/?api_key=YOUR_API_KEY
- Replace YOUR_API_KEY with your actual API key
Authorize the application
RTM will show you an auth token
Add this token to your .env file as RTM_AUTH_TOKEN

7. Restart Claude Desktop

After configuring, restart Claude Desktop to load the RTM tools.

Usage Examples

Once configured, you can use natural language with Claude:

"Create a task to review quarterly reports due next Friday"
"Show me all high priority tasks"
"Add a note to the 'Review Q4 budget' task"
"Set the estimate for 'Write documentation' to 2 hours"
"Set the location of 'Meet with client' to Downtown Office"
"Add the URL https://github.com/myproject to the 'Code review' task"
"Move all tasks tagged 'urgent' to my Work list"
"Mark the 'Buy groceries' task as complete"
"Show me what locations are available in RTM"
"Get a permalink for the 'Important meeting' task"

Security Notes

Credential Management

Configuration stored in .env file (project root) - NEVER commit this file
.gitignore protects it: .env* is already in .gitignore to prevent accidental commits
File permissions: Optional but recommended - chmod 600 .env to restrict access
Never commit API credentials to any repository
Regenerate credentials if you suspect they've been compromised
Environment variables: Alternative for CI/CD - set RTM_API_KEY, RTM_SHARED_SECRET, RTM_AUTH_TOKEN directly
Docker: For container deployment, use --env-file or pass credentials as environment variables
Config fallback: Credentials can also be loaded from ~/.config/rtm-mcp/config if .env not present

Access Permissions

The server has full access to your RTM account
It can create, modify, and delete any tasks and lists
Test carefully before using with important data

API Implementation Details

Rate Limiting

Implements RTM's required 1 request/second rate limit
Supports burst of up to 3 requests
Automatic rate limit enforcement with sleep delays

Error Handling

Comprehensive error handling for all RTM API responses
User-friendly error messages
Proper handling of edge cases (empty lists, missing tasks, etc.)

Data Handling

Timeline caching: Avoids repeated timeline API calls
List name caching: Provides user-friendly list names in responses
Natural language parsing: Due dates, start dates, and estimates support human-friendly input
Array handling: Properly handles RTM's array-wrapped single responses

Technical Requirements

Three ID system: Most task operations require list_id, taskseries_id, and task_id
API versioning: Some features require specific RTM API versions
Parameter signing: All API calls properly signed with MD5 hash

Known Limitations

RTM API Limitations

Subtask listing: RTM API doesn't provide direct subtask enumeration (our implementation uses a workaround)
Pro features: Some features (like subtasks) require RTM Pro subscription

Minor Implementation Gaps

Smart Add parsing: Uses standard task creation instead of RTM's Smart Add syntax
Contacts/Sharing: RTM's contact and task sharing features not implemented
Groups: RTM group functionality not implemented

Development & Testing

File Structure

rtm-mcp/
├── rtm_mcp.py             # CLI entry point
├── rtm_client.py          # RTM API HTTP client
├── rtm_server.py          # MCP server with 29 tools
├── rtm_limiter.py         # Rate limiting implementation
├── pyproject.toml         # Python project configuration
├── uv.lock                # Locked dependencies
├── .env.example           # Credentials template
├── Dockerfile.python      # Python container image
├── README.md              # This file
├── .gitignore             # Security configuration
└── tests/                 # Test suite
    ├── conftest.py        # Pytest configuration
    ├── test_imports.py    # Module import tests
    ├── test_unit.py       # Unit tests (no API needed)
    └── test_integration.py # Integration tests (with RTM API)

Testing

Run the comprehensive test suite:

# Install dev dependencies
uv pip install -e ".[dev]"

# Run all tests
pytest tests/ -v

# Run only unit tests (no RTM API needed)
pytest tests/test_unit.py -v

# Run integration tests (requires .env credentials)
pytest tests/test_integration.py -v -s

# Run specific test
pytest tests/test_integration.py::TestConnection::test_connection -v

Test Coverage:

✅ 4 Import Tests: Verify all modules load correctly
✅ 6 Unit Tests: Core functionality without API (protocol, rate limiting)
✅ 12 Integration Tests: Real RTM API calls (connection, tasks, metadata)
Total: 22 tests

Contributing

When adding new features:

Write tests first (TDD)
Implement the feature in the appropriate module
Update rtm_server.py if adding a new MCP tool
Run full test suite: pytest tests/ -v
Test via Claude Desktop
Update this README

Troubleshooting

Common Issues

"Login failed / Invalid auth token"

RTM_AUTH_TOKEN is not set or invalid
Some operations work without it (read-only)
Get a valid token from RTM OAuth flow (see "Getting Your Auth Token" section)

"Invalid API Key"

RTM_API_KEY is not set or invalid
Verify your API key at https://www.rememberthemilk.com/services/api/keys.rtm
Check .env file has correct key without extra whitespace

"Method not valid for requested version"

Some RTM API methods require specific API versions
Our implementation handles this automatically

"Timeline required"

RTM write operations need a timeline
Our implementation caches timelines automatically

"Tool not found in Claude Desktop"

Restart Claude Desktop after configuration changes
Verify MCP configuration file syntax (JSON must be valid)
Check that Python is in your PATH

pytest: command not found

Install dev dependencies: uv pip install -e ".[dev]"
Or install pytest directly: pip install pytest

Testing & Debugging

# Test your configuration by running unit tests (no API needed)
pytest tests/test_unit.py -v

# Test with integration tests (requires .env credentials)
pytest tests/test_integration.py -v -s

# Check credentials are loaded correctly
python3 -c "from dotenv import load_dotenv; import os; load_dotenv(); print(f'API_KEY: {os.getenv(\"RTM_API_KEY\")[:10]}...')"

# Test Python can import modules
python -c "import rtm_client; import rtm_server; print('✅ All modules loaded')"

Getting Help

Check RTM API documentation: https://www.rememberthemilk.com/services/api/
Verify your RTM account status and API limits
Run unit tests to verify setup: pytest tests/test_unit.py -v
Check .env file is in project root and not gitignored
Verify credentials don't have extra whitespace

License

This project is for personal use with Remember The Milk's API. Respect RTM's terms of service and API usage guidelines.

Name		Name	Last commit message	Last commit date
Latest commit History 47 Commits
.github/workflows		.github/workflows
tests		tests
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
Dockerfile		Dockerfile
README.md		README.md
docker-compose.yml		docker-compose.yml
pyproject.toml		pyproject.toml
rtm_client.py		rtm_client.py
rtm_limiter.py		rtm_limiter.py
rtm_mcp.py		rtm_mcp.py
rtm_server.py		rtm_server.py
uv.lock		uv.lock

moellenbeck/rtm-mcp

Folders and files

Latest commit

History

Repository files navigation