Uses YAML format for human-readable persistence of todo data, storing all todo items with their metadata in a structured YAML file
MCP Todo List Manager
A Model Context Protocol (MCP) server that provides todo list management functionality with YAML-based persistence. This server integrates with Claude Desktop and other MCP clients to offer natural language todo management.
Features
List todos: View all todo items with their status and timestamps
Add todos: Create new todo items with automatic timestamp tracking
Complete todos: Mark items as done with completion timestamps
Delete todos: Remove todo items by ID
System timestamp: Independent utility for fetching current time
Quick Start
Clone and setup:
git clone <repository-url> cd MCPToDo python -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate pip install -r requirements.txtRun the server:
python main.pyTest with Claude Desktop (see Integration Guide)
Architecture
Single-file MCP server:
main.py
contains the complete implementationYAML persistence: Human-readable storage in
~/.todos.yaml
Atomic writes: Safe file operations prevent data corruption
UUID identifiers: Unique identifiers for each todo item
ISO 8601 timestamps: Standard timestamp format for creation and completion
Usage
Running the Server
Start the MCP server:
With Logging (to monitor Claude Desktop requests):
The server will start and expose the following MCP tools:
Claude Desktop Integration
For detailed instructions on integrating with Claude Desktop, see claude-desktop-integration.md.
Quick Setup:
Add server configuration to Claude Desktop MCP settings
Restart Claude Desktop
Use natural language to manage todos through Claude
Example: "Add a todo to buy groceries" → Claude uses the MCP tools automatically
Available Tools
list_todos
Lists all todo items
Returns: Array of todo objects
add_todo
Creates a new todo item
Parameters:
description
(string)Returns: Created todo object with ID
complete_todo
Marks a todo as completed
Parameters:
id
(string)Returns: Updated todo object or null if not found
delete_todo
Removes a todo item
Parameters:
id
(string)Returns: Boolean success status
get_timestamp
Utility function for current system time
Returns: ISO 8601 formatted timestamp
Data Storage
Todos are stored in ~/.todos.yaml
with the following structure:
File Permissions
The todo YAML file requires specific permissions for secure operation:
Required Permissions for
Owner: Read + Write (rw-) - Required for loading and saving todos
Group: No access (---) - Security best practice
Others: No access (---) - Prevents unauthorized access
Setting Correct Permissions:
Automatic Permission Setting: The application automatically sets secure permissions (600) when creating new todo files.
Development
Testing
The project includes comprehensive unit tests covering all core functionality:
Run the full test suite:
Run tests with coverage information:
Test Coverage
✅ All 21 tests pass successfully
TestHelperFunctions (6 tests): File operations, data loading/saving, timestamp generation, file permissions
TestMCPTools (9 tests): CRUD operations for todos, error handling, edge cases
TestLogging (4 tests): Logging configuration, log levels, file output, MCP request logging
TestIntegration (2 tests): Complete workflows and data persistence
Test Categories
File Operations
Loading from non-existent files
Empty file handling
Valid YAML data processing
Atomic file saving
Todo Management
Adding single and multiple todos
Completing existing and non-existent todos
Deleting todos with proper cleanup
Listing todos in various states
Integration Workflows
Complete todo lifecycle (create → complete → delete)
Data persistence across server restarts
Concurrent operations safety
Code Quality
Check code style:
Current Status: ✅ All 21 tests pass. Minor style warnings present (line length, whitespace)
Development Setup
Install development dependencies from
requirements.txt
Use virtual environment for isolation
Follow PEP 8 style guidelines
Run tests before committing changes
Security & Permissions
File System Permissions
Todo Data File (~/.todos.yaml
)
Required:
600
(rw-------) - Owner read/write onlyPurpose: Protects personal todo data from other users
Auto-set: Application creates file with secure permissions
Application Directory
Python files:
644
(rw-r--r--) - Standard read permissionsVirtual environment:
755
(rwxr-xr-x) - Standard directory permissionsTemporary files:
600
(rw-------) - Used during atomic writes
Home Directory Considerations
Parent directory: Must have execute permission for user (
x
bit)Example: If using
~/Documents/todos.yaml
, ensure~/Documents/
is accessibleVerification:
ls -ld ~/
should show execute permission
Security Best Practices
1. File Location Security
2. Directory Permissions
3. Process Permissions
User Context: MCP server runs as current user
No Root Required: Application doesn't need elevated privileges
Isolation: Each user's todos are isolated by file system permissions
4. Network Security
Local Only: MCP server binds to local process communication
No Network Ports: Doesn't open TCP/UDP ports
Process Communication: Uses stdin/stdout for MCP protocol
Common Permission Issues
Issue: "Permission Denied" when accessing todo file
Issue: Cannot create todo file in directory
Issue: Application cannot access home directory
Multi-User Considerations
Separate User Data
Each user gets their own todo file:
~/.todos.yaml
No shared state between users
File system provides natural isolation
System Administrator Setup
Container/Docker Permissions
Security Limitations
⚠️ Current Security Gaps (See TODO.md for improvements):
No input validation on todo descriptions
No file size limits (potential DoS)
No encryption at rest
Uses
yaml.load()
instead ofyaml.safe_load()
(code execution risk)
Recommended Setup Checklist
Verify home directory has execute permission (
ls -ld ~/
)Use default location
~/.todos.yaml
or secure custom pathAvoid shared directories like
/tmp/
or/var/shared/
Run application as regular user (not root)
Check file permissions after first run (
ls -la ~/.todos.yaml
)Consider separate todo files for different contexts (work/personal)
Configuration
Environment Variables
TODO_FILE
: Custom location for todo storage (default:~/.todos.yaml
)LOG_LEVEL
: Logging verbosity - DEBUG, INFO, WARNING, ERROR (default:DEBUG
)LOG_FILE
: Log output file path (default:~/.todo-mcp-server.log
)
Other Settings
Timestamp Format: ISO 8601 with second precision (not configurable)
Usage Examples
Dependencies
mcp: MCP server framework (≥0.2.0)
ruamel.yaml: YAML processing with formatting preservation (≥0.18.6)
pytest: Testing framework (≥8.3.0)
flake8: Code style checker (≥7.1.0)
License
[Add license information]
Contributing
[Add contribution guidelines]
This server cannot be installed
local-only server
The server can only run on the client's local machine because it depends on local resources.
Enables natural language todo list management through Claude Desktop with YAML-based persistence. Supports creating, completing, deleting, and listing todo items with automatic timestamp tracking and secure file permissions.