Todo List MCP Server

A simple, beginner-friendly Model Context Protocol (MCP) server written in Python. It lets any MCP-compatible AI client (like Claude Desktop) manage a to-do list on your computer through five tools: add, view, get by ID, complete, and delete.

Built with the official MCP Python SDK (mcp[cli]) and its high-level FastMCP interface. Data is stored locally in a plain JSON file — no database required.

1. What This Project Does

This MCP server exposes 5 tools to any connected AI client:

All data lives in todos.json, created automatically the first time you add a todo.

Related MCP server: Task MCP Server

2. Project Structure

todo-mcp-server/
├── server.py          # Main MCP server — defines the 5 tools
├── storage.py          # Handles reading/writing todos.json
├── todos.json           # Auto-created data file (not committed to git)
├── requirements.txt     # Python dependencies     
├── .gitignore            # Files Git should ignore
└── README.md             

3. Setup

Prerequisites

• Python 3.10 or newer

• pip (comes with Python)

Steps

# 1. Clone or download this project, then move into it
cd todo-mcp-server

# 2. Create a virtual environment
python -m venv venv

# 3. Activate it
# Windows:
venv\Scripts\activate
# macOS/Linux:
source venv/bin/activate

# 4. Install dependencies
pip install -r requirements.txt

4. Running the Server

Option A — MCP Inspector (recommended for testing):

mcp dev server.py

This opens a browser-based UI where you can call each tool manually and see the JSON responses.

Option B — Install into Claude Desktop:

mcp install server.py --name "Todo List MCP Server"

This registers the server so Claude Desktop starts it automatically.

Option C — Run directly:

python server.py

5. Testing / Example Prompts (in Claude Desktop)

Once connected in Claude Desktop, try:

• "Add a todo: Buy groceries, with description Milk, eggs, and bread"

• "Show me all my todos"

• "Get the todo with ID 1"

• "Mark todo 1 as completed"

• "Delete todo 2"

6. Architecture

 MCP Client (Claude Desktop)
          │  (stdio / JSON-RPC)
          ▼
     server.py  (FastMCP tools)
          │
          ▼
     storage.py (reads/writes JSON)
          │
          ▼
     todos.json  (local data file)

The client never touches the JSON file directly — it only calls tools, and the server decides how the data is stored. This separation is a core MCP design idea: the client doesn't need to know how a tool works internally, only what it does.

7. Learning Outcomes

Through this project I learned:

• What the Model Context Protocol (MCP) is and how it standardizes tool access for LLMs

• The difference between an MCP server, client, and tools/resources/prompts

• How to use the official Python SDK's FastMCP interface to build tools quickly from plain Python functions and type hints

• How to store and manage data locally with a JSON file

• How to connect and test a custom MCP server inside Claude Desktop

• How to package, document, and publish a small Python project on GitHub

• The basics of publishing an MCP server to a marketplace like Smithery

License

MIT — free to use, modify, and share.

Author

Haseeba Yasin

If you found this project helpful, feel free to ⭐ the repository.