Todo List MCP Server

1# Todo List MCP Server
2 
3A Model Context Protocol (MCP) server that provides a comprehensive API for managing todo items.
4 
5<a href="https://glama.ai/mcp/servers/kh39rjpplx">
6  <img width="380" height="200" src="https://glama.ai/mcp/servers/kh39rjpplx/badge" alt="Todo List Server MCP server" />
7</a>
8 
9> **📚 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.
10 
11## Features
12 
13- **Create todos**: Add new tasks with title and markdown description
14- **Update todos**: Modify existing tasks
15- **Complete todos**: Mark tasks as done
16- **Delete todos**: Remove tasks from the list
17- **Search todos**: Find tasks by title or creation date
18- **Summarize todos**: Get a quick overview of active tasks
19 
20## Tools
21 
22This MCP server exposes the following tools:
23 
241. `create-todo`: Create a new todo item
252. `list-todos`: List all todos
263. `get-todo`: Get a specific todo by ID
274. `update-todo`: Update a todo's title or description
285. `complete-todo`: Mark a todo as completed
296. `delete-todo`: Delete a todo
307. `search-todos-by-title`: Search todos by title (case-insensitive partial match)
318. `search-todos-by-date`: Search todos by creation date (format: YYYY-MM-DD)
329. `list-active-todos`: List all non-completed todos
3310. `summarize-active-todos`: Generate a summary of all active (non-completed) todos
34 
35## Installation
36 
37```bash
38# Clone the repository
39git clone https://github.com/RegiByte/todo-list-mcp.git
40cd todo-list-mcp
41 
42# Install dependencies
43npm install
44 
45# Build the project
46npm run build
47```
48 
49## Usage
50 
51### Starting the Server
52 
53```bash
54npm start
55```
56 
57### Configuring with Claude for Desktop
58 
59#### Claude Desktop
60 
61Add this to your `claude_desktop_config.json`:
62 
63```json
64{
65  "mcpServers": {
66    "todo": {
67      "command": "node",
68      "args": ["/absolute/path/to/todo-list-mcp/dist/index.js"]
69    }
70  }
71}
72```
73 
74#### Cursor
75 
76- Go to "Cursor Settings" -> MCP
77- Add a new MCP server with a "command" type
78- Add the absolute path of the server and run it with node
79- Example: node /absolute/path/to/todo-list-mcp/dist/index.js
80 
81### Example Commands
82 
83When using with Claude for Desktop or Cursor, you can try:
84 
85- "Create a todo to learn MCP with a description explaining why MCP is useful"
86- "List all my active todos"
87- "Create a todo for tomorrow's meeting with details about the agenda in markdown"
88- "Mark my learning MCP todo as completed"
89- "Summarize all my active todos"
90 
91## Project Structure
92 
93This project follows a clear separation of concerns to make the code easy to understand:
94 
95```
96src/
97├── models/       # Data structures and validation schemas
98├── services/     # Business logic and database operations
99├── utils/        # Helper functions and formatters
100├── config.ts     # Configuration settings
101├── client.ts     # Test client for local testing
102└── index.ts      # Main entry point with MCP tool definitions
103```
104 
105## Learning from This Project
106 
107This project is designed as an educational resource. To get the most out of it:
108 
1091. Read the [GUIDE.md](GUIDE.md) for a comprehensive explanation of the design
1102. Study the heavily commented source code to understand implementation details
1113. Use the test client to see how the server works in practice
1124. Experiment with adding your own tools or extending the existing ones
113 
114## Development
115 
116### Building
117 
118```bash
119npm run build
120```
121 
122### Running in Development Mode
123 
124```bash
125npm run dev
126```
127 
128## License
129 
130MIT