TodoList

You can manage ToDoList .tdl files programmatically with this Python MCP Server. It provides full CRUD operations, hierarchical task support, and rich metadata while staying compatible with the ToDoList desktop application, making it easy to automate task workflows and keep data in sync.

How to use

Install and run the server locally, then use an MCP client to perform tasks operations such as creating, reading, updating, and deleting tasks. You can query all tasks, filter by due dates or priorities, move tasks within the hierarchy, and read or analyze the structure of your ToDoList files. The server exposes a set of functions you call from your MCP client, returning structured task data that mirrors the ToDoList XML format.

How to install

Prerequisites: you need Python 3.7 or higher and a ToDoList application to work with .tdl files.

Step 1: Open a terminal and clone the project repository.

git clone https://github.com/ispyridis/todolist-mcp.git
cd todolist-mcp

Step 2: Install the required Python dependencies.

pip install -r requirements.txt

Step 3: Start the MCP server locally.

python tdl_mcp_server.py

Configuration

The server uses a ToDoList file path as its default data source. You can change the target .tdl file by editing the DEFAULT_TDL_FILE setting inside the server script so it points to the ToDoList file you want to manage.

Troubleshooting

If you encounter issues, verify the ToDoList file exists and is accessible, ensure the XML format is valid, check file write permissions, and close ToDoList if the file is locked by another process.

Enable verbose startup logs to diagnose startup problems by running the server in the foreground with standard output streaming.

Tools and capabilities

This server supports a comprehensive set of task operations, including creation, retrieval, updates, deletion, hierarchy management, and search capabilities. It also provides file status checks and XML structure analysis for ToDoList files.

Notes

The server is designed to work with live ToDoList files, preserving compatibility with the ToDoList application while enabling programmatic control over tasks and their metadata.

Available tools

get_my_tasks

Retrieve all tasks from the main ToDoList file, returning a structured list of tasks with their metadata.

get_today_tasks

Fetch tasks due on a specific date or today, supporting date-based filtering.

add_task

Create a new task with full metadata such as title, description, due date, priority, and category.

update_task

Update an existing task by ID, including progress, priority, and assignments.

move_task

Move a task to a different position in the hierarchical structure.

get_task

Get detailed information about a specific task by its ID.

search_tasks

Filter and search tasks based on criteria like term, category, priority, and completion status.

get_file_status

Check the status and statistics of the connected ToDoList file.

read_any_tdl_file

Read tasks from any ToDoList .tdl file to inspect structure and data.

analyze_structure

Analyze the XML structure of ToDoList files to understand layout and metadata.