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:
- Run the server:
- Test with Claude Desktop (see Integration Guide)
Architecture
- Single-file MCP server:
main.py
contains the complete implementation - YAML 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 ~/.todos.yaml
:
- 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 only - Purpose: 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 permissions - Virtual environment:
755
(rwxr-xr-x) - Standard directory permissions - Temporary 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 accessible - Verification:
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 path - Avoid 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.