Todo MCP Server

A robust, persistent task management server built on the Model Context Protocol (MCP) using Python and FastMCP.

---

Overview

The Todo MCP Server provides language models and AI agents with a persistent, stateful task management interface. Built using the official Python MCP SDK (FastMCP), it exposes tools that allow AI assistants to create, track, filter, and complete tasks directly within their workflow.

State is persisted locally to structured JSON storage (tasks.json), ensuring task data survives server restarts, client reconnections, and multi-turn agent sessions. Communication follows the MCP specification using JSON-RPC 2.0 over standard input/output (stdio).

---

Architecture & Data Flow

+-------------------------------------------------------------------+
|                        MCP Host / AI Client                       |
|               (Claude Desktop, Cursor, Antigravity)               |
+-------------------------------------------------------------------+
                                  |
                   JSON-RPC 2.0 over stdin / stdout
                                  v
+-------------------------------------------------------------------+
|                       Todo MCP Server                             |
|                                                                   |
|   +-----------------------------------------------------------+   |
|   |                       FastMCP Engine                      |   |
|   |  - Protocol negotiation & schema reflection               |   |
|   |  - Tool dispatch & argument validation (Pydantic/Typing)  |   |
|   +-----------------------------------------------------------+   |
|                                 |                                 |
|   +-----------------------------+-----------------------------+   |
|   |                             |                             |   |
|   v                             v                             v   |
| [ add_task ]             [ list_tasks ]             [ complete_task ]
|   |                             |                             |   |
|   +-----------------------------+-----------------------------+   |
|                                 |                                 |
|                                 v                                 |
|   +-----------------------------------------------------------+   |
|   |                    Storage Controller                     |   |
|   |  - Atomic read/write operations                           |   |
|   |  - Schema serialization with ISO 8601 UTC timestamps      |   |
|   +-----------------------------------------------------------+   |
+-------------------------------------------------------------------+
                                  |
                                  v
+-------------------------------------------------------------------+
|                      Local Storage: tasks.json                    |
+-------------------------------------------------------------------+

---

Tools Reference

The server exposes three distinct tools for full task lifecycle management.

1. add_task

Creates a new task item and appends it to persistent storage.

• Description: Add a new task to the todo list.
• Parameters:
  • title (string, required): Description of the task. Length must be between 1 and 200 characters.
  • priority (string, optional): Urgency level. Accepted values: "low", "medium", "high". Default: "medium".
• Validation Rules:
  • Empty or whitespace-only strings are rejected.
  • Titles exceeding 200 characters return an error.
  • Non-conforming priority values fail schema validation.

Example Request:

{
  "title": "Implement integration test suite",
  "priority": "high"
}

Example Response:

Task added!
  ID:       1
  Title:    Implement integration test suite
  Priority: high
  Status:   pending

---

2. list_tasks

Retrieves saved tasks with optional filtering by completion status.

• Description: List tasks from the todo list with optional status filtering.
• Parameters:
  • status (string, optional): Filter criteria. Accepted values: "all", "pending", "done". Default: "all".
• Formatting: Returns a formatted ASCII table summarizing task IDs, status indicators, priority levels, and titles.

Example Request:

{
  "status": "pending"
}

Example Response:

Tasks (pending) — 2 found:

  ID  Status    Priority Title
————  ————————— ———————— ————————————————————————————————————————
   1  pending   high     Implement integration test suite
   2  pending   medium   Update project documentation

---

3. complete_task

Marks an existing task as completed by its unique integer identifier.

• Description: Mark a task as done by its numeric ID.
• Parameters:
  • task_id (integer, required): The unique numeric identifier assigned to the task.
• Behavior:
  • Updates the task status to "done".
  • Sets the completed_at field to the current ISO 8601 UTC timestamp.
  • Idempotent: If the task is already completed, the tool notifies the client without corrupting timestamps.
  • If the ID does not exist, an error response is returned with the list of currently valid IDs.

Example Request:

{
  "task_id": 1
}

Example Response:

Task 1 completed!
  Title:        Implement integration test suite
  Completed at: 2026-08-20T09:46:17.466797+00:00

---

Tool Summary Table

Tool	Purpose	Parameters	Return Type
add_task	Create a new task	title (str, required)<br>priority ("low" | "medium" | "high", default: "medium")	string (Confirmation details)
list_tasks	Query stored tasks	status ("all" | "pending" | "done", default: "all")	string (Formatted table)
complete_task	Mark a task as completed	task_id (int, required)	string (Completion status & timestamp)

---

Data Model & Persistence

Task records are serialized as UTF-8 encoded JSON arrays. By default, records are stored in tasks.json in the current working directory. The storage file path can be customized via the TODO_FILE environment variable.

Schema Definition

[
  {
    "id": 1,
    "title": "Implement integration test suite",
    "priority": "high",
    "status": "done",
    "created_at": "2026-08-20T09:46:17.362387+00:00",
    "completed_at": "2026-08-20T09:46:17.466797+00:00"
  },
  {
    "id": 2,
    "title": "Update project documentation",
    "priority": "medium",
    "status": "pending",
    "created_at": "2026-08-20T09:46:17.384689+00:00",
    "completed_at": null
  }
]

Field Specifications

• id (integer): Auto-incrementing positive integer identifier.
• title (string): Task description string (1-200 chars).
• priority (string): Urgency classification ("low", "medium", "high").
• status (string): Lifecycle stage ("pending" or "done").
• created_at (string): ISO 8601 formatted UTC timestamp recorded at creation.
• completed_at (string | null): ISO 8601 formatted UTC timestamp recorded upon completion.

---

Requirements

• Python: Version 3.10 or higher
• Dependencies:
  • mcp[cli]>=1.28,<2

---

Installation & Setup

1. Clone the Repository

git clone https://github.com/moazhassan751/mcp-todo-server.git
cd mcp-todo-server

2. Create a Virtual Environment

# Linux/macOS
python3 -m venv .venv
source .venv/bin/activate

# Windows
python -m venv .venv
.venv\Scripts\activate

3. Install Dependencies

pip install -r requirements.txt

---

Execution Modes

Standard Execution (stdio)

Run the server directly for production or MCP host integration:

python server.py

Developer Inspection (MCP Inspector)

The MCP Inspector provides an interactive browser-based interface to test tools, inspect schemas, and simulate requests:

mcp dev server.py

The inspector will launch and provide a local interface URL (typically http://localhost:6274).

---

Client Integration Guide

To connect the Todo MCP Server to your preferred AI environment, configure the server in your client's MCP configuration file.

Claude Desktop

Edit your Claude Desktop configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "todo-server": {
      "command": "python",
      "args": ["/absolute/path/to/mcp-todo-server/server.py"]
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project or global directory:

{
  "mcpServers": {
    "todo-server": {
      "command": "python",
      "args": ["/absolute/path/to/mcp-todo-server/server.py"]
    }
  }
}

Antigravity IDE

Add to .agents/mcp_config.json in your workspace:

{
  "mcpServers": {
    "todo-server": {
      "command": "python",
      "args": ["/absolute/path/to/mcp-todo-server/server.py"]
    }
  }
}

---

Testing & Verification

The repository includes comprehensive automated test scripts:

Standard Test Suite

Tests basic tool calls, parameter validations, and output formatting:

python test_server.py

Multi-Session Audit Test

Simulates separate client connections, restarts the server process across sessions, and validates that persistent storage correctly retains state:

python audit_test.py

---

Project Structure

mcp-todo-server/
├── server.py           # Core MCP server definition and tool implementations
├── test_server.py      # Automated stdio protocol unit tests
├── audit_test.py       # Multi-session persistence and edge-case verification
├── requirements.txt    # Package dependencies
├── .gitignore          # Version control ignore definitions
└── README.md           # Technical documentation and integration reference

---

License

This project is open source and available under the MIT License.