FastMCP Todo List Server

A powerful, feature-rich todo list server built with FastMCP that provides a comprehensive set of tools for managing todos. This server can be used with Claude Desktop to create, manage, and organize your tasks efficiently.

Features

- Rich Todo Management: Create, read, update, and delete todos with extensive metadata
- Advanced Filtering & Sorting: Filter by status, priority, tags, due dates, and more
- Search Capability: Search todos by title and description
- Automatic Backups: Automatic backups before any data changes
- Manual Backups: Create manual backups on demand
- Statistics: Get detailed statistics about your todos
- Data Validation: Comprehensive validation for all inputs
- Caching: Efficient caching to reduce file I/O
- Configurable: Configurable file paths via environment variables

Installation

1. Clone this repository:

   git clone https://github.com/DustyPolk/todo_mcp.git

   cd todo_mcp

   

2. Create and activate a virtual environment:

   python -m venv .venv

   # On Windows

   .venv\Scripts\activate

   # On macOS/Linux

   source .venv/bin/activate

   

3. Install the required packages:

   pip install fastmcp aiofiles

   

Running the Server

Run the server with:

python todolist_server.py

The server will start and be available for Claude Desktop to connect to.

Environment Variables

You can configure the server using the following environment variables:

- TODO_FILE: Path to the JSON file where todos are stored (default: todos.json in the same directory as the script)
- TODO_BACKUP_DIR: Path to the directory where backups are stored (default: backups in the same directory as the script)

Available Tools

The server provides the following tools:

add_todo

Add a new todo item.

Parameters:
- title: The title of the todo (required, max 100 chars)
- description: A detailed description (optional, max 1000 chars)
- due_date: Due date in YYYY-MM-DD format (optional)
- status: Status of the todo (optional, one of: pending, in_progress, done, cancelled)
- priority: Priority level (optional, one of: low, medium, high, critical)
- tags: List of tags for categorization (optional)

list_todos

List todos with filtering, sorting and pagination.

Parameters:
- status: Filter by status (optional, one of: pending, in_progress, done, cancelled)
- priority: Filter by priority (optional, one of: low, medium, high, critical)
- search: Search in title and description (optional)
- tag: Filter by tag (optional)
- due_date_filter: Filter by due date (optional, one of: overdue, today, upcoming, no_date)
- sort_by: Field to sort by (optional, default: id)
- sort_order: Sort order (optional, one of: asc, desc, default: asc)
- limit: Maximum number of todos to return (optional, default: 100)
- offset: Number of todos to skip (optional, default: 0)

get_todo

Get a todo by id.

Parameters:
- todo_id: The ID of the todo to retrieve

update_todo

Update a todo by id.

Parameters:
- todo_id: The ID of the todo to update
- title: New title (optional)
- description: New description (optional)
- due_date: New due date in YYYY-MM-DD format (optional)
- status: New status (optional, one of: pending, in_progress, done, cancelled)
- priority: New priority (optional, one of: low, medium, high, critical)
- tags: New list of tags (optional)

complete_todo

Mark a todo as complete by id.

Parameters:
- todo_id: The ID of the todo to mark as complete

delete_todo

Delete a todo by id.

Parameters:
- todo_id: The ID of the todo to delete

batch_delete_todos

Delete multiple todos by ids.

Parameters:
- todo_ids: List of todo IDs to delete

create_backup

Create a manual backup of the todos file.

Parameters: None

get_statistics

Get statistics about todos.

Parameters: None

Data Structure

Todos are stored with the following structure:

{
  "id": 1,
  "title": "Complete project report",
  "description": "Finish the quarterly project report",
  "due_date": "2025-05-20",
  "status": "pending",
  "priority": "high",
  "tags": ["work", "quarterly"],
  "created_at": "2025-05-09T12:00:00.000000",
  "updated_at": "2025-05-09T12:00:00.000000"
}

License

MIT