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](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
Usage
Starting the Server
Configuring with Claude for Desktop
Claude Desktop
Add this to your `claude_desktop_config.json`:
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:
Learning from This Project
This project is designed as an educational resource. To get the most out of it:
- Read the [GUIDE.md](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
Running in Development Mode
License
MIT