What is Todo Mcp

todo_mcp is a simple and effective MCP server designed to manage your todos efficiently. It provides a powerful interface for creating, organizing, and tracking tasks.

Use cases

Use cases include managing personal to-do lists, tracking project tasks in a team environment, organizing daily activities, and maintaining a backlog of tasks for software development.

How to use

To use todo_mcp, clone the repository, set up a virtual environment, install the required packages, and run the server. You can then connect to it using Claude Desktop to manage your todos.

Key features

Key features include rich todo management (CRUD operations), advanced filtering and sorting, search capability, automatic and manual backups, detailed statistics, data validation, efficient caching, and configurable file paths.

Where to use

todo_mcp can be used in various fields such as project management, personal task management, team collaboration, and any scenario where effective task tracking is needed.

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