MCP Task Manager

A beginner-friendly local task manager built with Python and the Model Context Protocol (MCP). It exposes five MCP tools for task management and one read-only resource for pending tasks. All data is persisted locally in tasks.json.

Features

• Create, list, retrieve, complete, and delete tasks

• Filter tasks by all, pending, or completed

• Read pending tasks through an MCP resource

• Persist task data in a local JSON file

• Return friendly validation and storage errors

• Verify behavior with automated pytest tests

Related MCP server: Task Manager MCP Server

MCP Capabilities

Project Structure

todo-mcp-server/
├── tests/
│   └── test_server.py
├── .gitignore
├── README.md
├── requirements.txt
├── server.py
└── tasks.json

Requirements

• Python 3.11 recommended

• Node.js and npm for MCP Inspector

• uv for launching the server from Inspector

• Git for version control

Installation on Windows

git clone https://github.com/YOUR-USERNAME/todo-mcp-server.git
cd todo-mcp-server
python -m venv .venv
.venv\Scripts\activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
python -m pip install uv

Verify the installation:

python --version
mcp version
uv --version

Run the Tests

python -m pytest tests -v
python -m py_compile server.py

The expected test result is 27 passed.

Run with MCP Inspector

From the activated virtual environment, run:

mcp dev server.py

Keep the terminal open. In the browser:

1. Keep the transport type set to STDIO.

2. Click Connect once.

3. Open Tools to discover and run the five tools.

4. Open Resources to read tasks://pending.

5. Press Ctrl+C in the terminal when finished.

Example Demo Flow

1. Call add_task:

   {
     "title": "Learn MCP",
     "description": "Complete the beginner MCP project"
   }

2. Call list_tasks with {"status": "all"}.

3. Call get_task with {"task_id": 1}.

4. Call complete_task with {"task_id": 1}.

5. Read tasks://pending; the completed task should be excluded.

6. Call delete_task with {"task_id": 1}.

7. Call get_task with {"task_id": 99} to demonstrate a friendly error.

Task Data Format

{
  "id": 1,
  "title": "Learn MCP",
  "description": "Complete the beginner MCP project",
  "completed": false,
  "created_at": "2026-09-12T10:00:00+00:00"
}

Troubleshooting

uv is not recognized

python -m pip install uv
uv --version

Inspector shows Request timed out

• Confirm that uv --version works.

• Keep the mcp dev server.py terminal running.

• Do not repeatedly click Connect.

• Check the terminal for a server startup error.

ModuleNotFoundError: No module named 'mcp'

.venv\Scripts\activate
python -m pip install -r requirements.txt

Tools do not appear

The Tools and Resources tabs appear only after a successful server connection.

MCP Concepts Demonstrated

• An MCP client, such as Inspector, discovers and calls server capabilities.

• A tool performs an operation and may change persisted data.

• A resource provides read-only data.

• The stdio transport exchanges MCP JSON-RPC messages through standard input and output.

• Python type hints and docstrings help generate tool schemas.

Do not use print() for diagnostics in a stdio MCP server because stdout carries protocol messages. Use Python logging, which writes to stderr.

License

This project is intended for educational use.