FastMCP Todo List Server

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