todo list mcp server
š Personal To-Do List MCP Server
A minimalistic and functional Model Context Protocol (MCP) server that provides AI assistants with a robust local To-Do list manager. This server demonstrates how an AI can manage local state and interact with persistent data (CRUD operations) without requiring external APIs or complex databases.
š Live Demo & Media
Live Registry Listing: Glama MCP Server
Related MCP server: Todo MCP Server
šø Screenshots

⨠Key Features
š¤ Native AI Integration: Works seamlessly with Claude Desktop, Cursor, and Antigravity.
š ļø Complete CRUD Operations: Add, list, complete, and delete tasks.
š Real-time Summaries: Provides read-only resources summarizing pending vs. completed tasks.
š Private Local Storage: Stores data strictly on your local machine using JSON.
āļø Zero Configuration: Works entirely out of the box with modern Python packaging.
š ļø Tech Stack Table
Category | Technology | Purpose |
Protocol | Model Context Protocol (MCP) | AI-to-Tool communication standard |
Language | Python 3.10+ | Core logic and execution |
SDK |
| Official Anthropic SDK for Python |
Package Manager |
| Modern dependency management |
Database | Local JSON File | Persistent local state storage |
āļø How It Works
Tool Invocation: The AI client sends a JSON-RPC request to the MCP server (e.g.,
add_task).Execution: The Python server parses the local
todos.jsonfile.Modification: The server updates the JSON file with the new task and saves it.
Response: The server returns a success confirmation back to the AI client.
šļø Project Architecture
graph LR
A[AI Assistant] <-->|JSON-RPC via stdio| B[Todo MCP Server]
B -->|Read/Write| C[(todos.json)]
B --> D[Tools: add, list, delete, complete]
B --> E[Resources: todo://summary]š Project Structure
āāā docs/ # Learning outcomes and documentation
ā āāā inspector.png
ā āāā resend-experience.md
āāā src/
ā āāā todo_mcp/ # Core MCP server package
ā āāā __init__.py
ā āāā __main__.py # Execution entrypoint
ā āāā server.py # Tools and resources logic
āāā .gitignore
āāā pyproject.toml # Modern Python package configuration
āāā README.mdš» Local Setup & Installation
Prerequisites
Python 3.10 or higher
Node.js (for
npxif using the Inspector)
Installation
Clone the repository and install it locally using pip:
git clone https://github.com/Arslan-Codes097/todo-list-mcp-server.git
cd todo-list-mcp-server
pip install .Running Locally (Inspector)
To test the tools in the interactive MCP Inspector UI:
npx @modelcontextprotocol/inspector python -m todo_mcpConnecting to an AI Client (Zero-Install)
The easiest way to use this server is via uvx. It will automatically download and run the server without you needing to clone the repository manually.
Add the following to your client's config.json:
{
"mcpServers": {
"todo-mcp": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/Arslan-Codes097/todo-list-mcp-server.git",
"python",
"-m",
"todo_mcp"
]
}
}
}š¤ Author & Credits
Arslan
GitHub: @Arslan-Codes097
Built as a hands-on exploration of the Model Context Protocol.
Available Tools
4 toolsadd_taskB
Add a new task to the todo list.
Inputs: task (required). Returns: result
complete_taskA
Mark a task as completed using its ID (index).
Inputs: task_id (required). Returns: result
delete_taskA
Delete a task from the list using its ID.
Inputs: task_id (required). Returns: result
list_tasksA
List all tasks in the todo list.
Inputs: no named parameters. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogā¦
TDQS
Scored across 4 tools
Each tool has a distinct purpose: add, list, complete, and delete tasks. There is no ambiguity or overlap between them.
All tools follow the consistent verb_noun pattern (add_task, list_tasks, complete_task, delete_task), making the naming predictable and clear.
With just 4 tools, the server is tightly scoped to the core operations of a todo list, and each tool is necessary and sufficient for basic task management.
The tools cover the full lifecycle of a todo item: create (add_task), read (list_tasks), update (complete_task), and delete (delete_task). No essential operations are missing for a simple todo list.
Maintenance
Related MCP Connectors
Official Todoist MCP server. Manage tasks and projects. Hosted, no API key needed.
An MCP server that used to create notes
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceThis MCP server provides tools to manage a todo list with CRUD operations, enabling listing, creating, updating, and deleting todos.-
- AlicenseNot gradedqualityDmaintenanceA simple MCP server for managing todo items with SQLite database storage, supporting add, list, and remove operations.13 npm6ISC
- AlicenseNot gradedqualityDmaintenanceA CRUD todo list server that exposes tools to create, list, and conclude tasks, compatible with any MCP host.6 npmMIT
- AlicenseBqualityCmaintenanceA basic MCP server for managing a todo list stored in a local JSON file, enabling task creation, completion, listing, and daily summary generation.26 npmMIT