Skip to main content
Glama
todo list mcp server

todo list mcp server

šŸ“ Personal To-Do List MCP Server

Python 3.10+ MCP License: MIT

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

Related MCP server: Todo MCP Server

šŸ“ø Screenshots

MCP Inspector Testing

✨ 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

mcp[cli] (FastMCP)

Official Anthropic SDK for Python

Package Manager

pip / pyproject.toml

Modern dependency management

Database

Local JSON File

Persistent local state storage

āš™ļø How It Works

  1. Tool Invocation: The AI client sends a JSON-RPC request to the MCP server (e.g., add_task).

  2. Execution: The Python server parses the local todos.json file.

  3. Modification: The server updates the JSON file with the new task and saves it.

  4. 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 npx if 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_mcp

Connecting 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

Built as a hands-on exploration of the Model Context Protocol.

Available Tools

4 tools
add_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

    A4/5.0

    Scored across 4 tools

    Disambiguation5/5

    Each tool has a distinct purpose: add, list, complete, and delete tasks. There is no ambiguity or overlap between them.

    Naming Consistency5/5

    All tools follow the consistent verb_noun pattern (add_task, list_tasks, complete_task, delete_task), making the naming predictable and clear.

    Tool Count5/5

    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.

    Completeness5/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers