FastMCP Todo List Server

Created By

DustyPolk7 months ago

A simple and effective MCP server to manage your todos

Content

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

Clone this repository:

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

Create and activate a virtual environment:

python -m venv .venv
# On Windows
.venv\Scripts\activate
# On macOS/Linux
source .venv/bin/activate

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"
}