Todo List MCP Server

A Model Context Protocol (MCP) server that provides a comprehensive API for managing todo items.

📚 Learning Resource: This project is designed as an educational example of MCP implementation. See GUIDE.md for a comprehensive explanation of how the project works and why things are implemented the way they are.

Features

Create todos: Add new tasks with title and markdown description
Update todos: Modify existing tasks
Complete todos: Mark tasks as done
Delete todos: Remove tasks from the list
Search todos: Find tasks by title or creation date
Summarize todos: Get a quick overview of active tasks

Tools

This MCP server exposes the following tools:

create-todo: Create a new todo item
list-todos: List all todos
get-todo: Get a specific todo by ID
update-todo: Update a todo's title or description
complete-todo: Mark a todo as completed
delete-todo: Delete a todo
search-todos-by-title: Search todos by title (case-insensitive partial match)
search-todos-by-date: Search todos by creation date (format: YYYY-MM-DD)
list-active-todos: List all non-completed todos
summarize-active-todos: Generate a summary of all active (non-completed) todos

Installation

# Clone the repository
git clone https://github.com/RegiByte/todo-list-mcp.git
cd todo-list-mcp

# Install dependencies
npm install

# Build the project
npm run build

Usage

Starting the Server

npm start

Configuring with Claude for Desktop

Claude Desktop

Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "todo": {
      "command": "node",
      "args": ["/absolute/path/to/todo-list-mcp/dist/index.js"]
    }
  }
}

Cursor

Go to "Cursor Settings" -> MCP
Add a new MCP server with a "command" type
Add the absolute path of the server and run it with node
Example: node /absolute/path/to/todo-list-mcp/dist/index.js

Example Commands

When using with Claude for Desktop or Cursor, you can try:

"Create a todo to learn MCP with a description explaining why MCP is useful"
"List all my active todos"
"Create a todo for tomorrow's meeting with details about the agenda in markdown"
"Mark my learning MCP todo as completed"
"Summarize all my active todos"

Project Structure

This project follows a clear separation of concerns to make the code easy to understand:

src/
├── models/       # Data structures and validation schemas
├── services/     # Business logic and database operations
├── utils/        # Helper functions and formatters
├── config.ts     # Configuration settings
├── client.ts     # Test client for local testing
└── index.ts      # Main entry point with MCP tool definitions

Learning from This Project

This project is designed as an educational resource. To get the most out of it:

Read the GUIDE.md for a comprehensive explanation of the design
Study the heavily commented source code to understand implementation details
Use the test client to see how the server works in practice
Experiment with adding your own tools or extending the existing ones

Development

Building

npm run build

Running in Development Mode

npm run dev

License

MIT