Skip to main content
Glama

TodoList MCP Server

by ispyridis

TodoList MCP Server

A comprehensive Python MCP server for managing ToDoList (.tdl) XML files. This server provides full CRUD operations for tasks in the ToDoList application format, allowing you to manage your tasks programmatically while maintaining compatibility with the ToDoList desktop application.

Features

  • Full CRUD Operations: Create, read, update, and delete tasks

  • Hierarchical Task Support: Handle nested tasks and subtasks

  • Rich Metadata: Support for priorities, due dates, categories, assignments, and progress tracking

  • Search and Filtering: Advanced task filtering by various criteria

  • ToDoList Compatibility: Full compatibility with ToDoList application XML format

  • Real-time Sync: Works with live ToDoList files

Prerequisites

  • Python 3.7 or higher

  • ToDoList application (for .tdl file creation)

Installation

  1. Clone this repository:

git clone https://github.com/yourusername/todolist-mcp.git cd todolist-mcp
  1. Install dependencies:

pip install -r requirements.txt

Configuration

By default, the server monitors D:\Projects\mylist.tdl. You can change this by modifying the DEFAULT_TDL_FILE constant in tdl_mcp_server.py.

Usage

Starting the Server

python tdl_mcp_server.py

Available Tools

Task Management

  • get_my_tasks: Get all tasks from your main ToDoList file

  • get_today_tasks: Get tasks due today (or specific date)

  • add_task: Create new tasks with full metadata

  • update_task: Update existing tasks

  • move_task: Move tasks to different positions in the hierarchy

  • get_task: Get detailed information about a specific task

Search and Filtering

  • search_tasks: Search and filter tasks by various criteria

File Operations

  • get_file_status: Check ToDoList file status and statistics

  • read_any_tdl_file: Read tasks from any .tdl file

  • analyze_structure: Analyze the XML structure of ToDoList files

Example MCP Configuration

Add to your MCP client configuration:

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

API Reference

Task Operations

Create a Task

add_task({ "title": "Complete project documentation", "description": "Write comprehensive README files", "due_date": "2024-12-31", "priority": "High", "category": "Documentation" })

Update a Task

update_task({ "task_id": "123", "percent_done": 75, "allocated_to": "John Doe", "priority": "Above Normal" })

Search Tasks

search_tasks({ "search_term": "documentation", "category": "Work", "completed": false, "priority": "High" })

Task Properties

Property

Type

Description

title

string

Task title

description

string

Detailed task description

due_date

string

Due date (YYYY-MM-DD format)

priority

enum

Low, Below Normal, Normal, Above Normal, High, Urgent

category

string

Task category or project

allocated_to

string

Person(s) assigned to the task

percent_done

integer

Completion percentage (0-100)

position

string

Hierarchical position (e.g., "1.2.3")

Project Structure

todolist-mcp/ ├── tdl_mcp_server.py # Main MCP server ├── requirements.txt # Python dependencies ├── test_server.py # Server tests ├── test_update_functionality.py # Update functionality tests ├── claude_desktop_config.json # Example MCP configuration ├── Introduction.tdl # Sample ToDoList file └── README.md # This file

ToDoList File Format

The server works with ToDoList's native XML format (.tdl files). Key features:

  • Hierarchical Structure: Tasks can have unlimited nested subtasks

  • Rich Metadata: Supports all ToDoList fields and properties

  • Position Tracking: Maintains task order and hierarchy

  • Compatibility: Files remain fully compatible with ToDoList application

Example Task Structure

<TASK ID="1" TITLE="Project Alpha" PRIORITY="1" DUEDATE="44927"> <CATEGORY>Work</CATEGORY> <ALLOCATEDTO>John Doe</ALLOCATEDTO> <TASK ID="2" TITLE="Research Phase" PERCENTDONE="100"> <TASK ID="3" TITLE="Market Analysis" PERCENTDONE="100"/> <TASK ID="4" TITLE="Competitor Review" PERCENTDONE="75"/> </TASK> </TASK>

Testing

Run the test suite:

python test_server.py python test_update_functionality.py

Integration with ToDoList Application

This MCP server is designed to work alongside the ToDoList desktop application:

  1. Live Editing: Modify files that ToDoList has open

  2. Real-time Updates: Changes appear immediately in ToDoList

  3. Backup Safety: ToDoList maintains automatic backups

  4. Format Preservation: All ToDoList-specific formatting is preserved

Advanced Features

Hierarchical Task Management

  • Create nested task structures

  • Move tasks between hierarchy levels

  • Maintain parent-child relationships

Position Management

# Add task at specific position add_task({"title": "New Task", "position": "1.2.3"}) # Move task to new location move_task({"task_id": "123", "new_position": "2.1"})

Flexible Searching

# Complex search example search_tasks({ "search_term": "urgent", "category": "Work", "priority": "High", "completed": false, "assigned_to": "John" })

Error Handling

The server provides comprehensive error handling:

  • File validation and format checking

  • Task ID validation

  • Date format verification

  • Hierarchy consistency checks

Performance Considerations

  • File Size: Optimized for large ToDoList files (1000+ tasks)

  • Memory Usage: Efficient XML parsing and manipulation

  • Concurrent Access: Safe for use with ToDoList application running

Troubleshooting

Common Issues

  1. File Access: Ensure the .tdl file exists and is accessible

  2. XML Format: Verify the file is a valid ToDoList XML format

  3. Permissions: Check file write permissions

  4. ToDoList Lock: Close ToDoList if experiencing file lock issues

Debug Mode

Enable detailed logging:

python -u tdl_mcp_server.py

Contributing

  1. Fork the repository

  2. Create a feature branch

  3. Add tests for new functionality

  4. Ensure ToDoList compatibility

  5. Submit a pull request

License

Licensed under the Apache License 2.0. See LICENSE file for details.

Support

For issues and questions, please open an issue on GitHub.

Changelog

v0.4.0

  • Added comprehensive task management

  • Improved hierarchical support

  • Enhanced search capabilities

  • Better error handling

v0.3.0

  • Added update functionality

  • Position management

  • File status checking

v0.2.0

  • Initial CRUD operations

  • Basic search functionality

v0.1.0

  • Initial release

  • Read-only operations

-
security - not tested
F
license - not found
-
quality - not tested

local-only server

The server can only run on the client's local machine because it depends on local resources.

Enables full management of ToDoList (.tdl) XML files with CRUD operations, hierarchical task support, and advanced filtering. Maintains compatibility with the ToDoList desktop application while allowing programmatic task management.

  1. Features
    1. Prerequisites
      1. Installation
        1. Configuration
          1. Usage
            1. Starting the Server
            2. Available Tools
            3. Example MCP Configuration
          2. API Reference
            1. Task Operations
            2. Task Properties
          3. Project Structure
            1. ToDoList File Format
              1. Example Task Structure
            2. Testing
              1. Integration with ToDoList Application
                1. Advanced Features
                  1. Hierarchical Task Management
                  2. Position Management
                  3. Flexible Searching
                2. Error Handling
                  1. Performance Considerations
                    1. Troubleshooting
                      1. Common Issues
                      2. Debug Mode
                    2. Contributing
                      1. License
                        1. Support
                          1. Changelog
                            1. v0.4.0
                            2. v0.3.0
                            3. v0.2.0
                            4. v0.1.0

                          MCP directory API

                          We provide all the information about MCP servers via our MCP API.

                          curl -X GET 'https://glama.ai/api/mcp/v1/servers/ispyridis/todolist-mcp'

                          If you have feedback or need assistance with the MCP directory API, please join our Discord server