Todo List MCP Server

A small Model Context Protocol server that turns a plain JSON file into a todo list an MCP-compatible client (Claude Desktop, Claude Code, Cursor, etc.) can read and manage on your behalf.

What it does

It exposes five tools and one resource:

Tool	Description
add_todo(text, priority)	Add a new task. priority is low, medium, or high.
list_todos(status)	List tasks. status is all, pending, or done.
complete_todo(todo_id)	Mark a task as done.
delete_todo(todo_id)	Remove a task permanently.
clear_completed()	Remove every completed task in one call.

Resource	Description
todos://all	Read-only JSON dump of every todo.

Data lives in todos.json next to server.py, so it survives restarts.

Setup

# 1. Clone / copy this folder
cd todo-mcp

# 2. Create a virtual environment and install dependencies
python3 -m venv venv
source venv/bin/activate   # Windows: venv\Scripts\activate
pip install -r requirements.txt

# 3. Run it directly to sanity-check it starts (Ctrl+C to stop)
python server.py

Connect it to an MCP client

Claude Desktop

Add this to your claude_desktop_config.json (Settings → Developer → Edit Config):

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

Restart Claude Desktop, and you'll see the todo tools available in the tool picker (hammer icon). Try: "Add 'finish MCP ticket' as a high priority todo, then show me everything pending."

MCP Inspector (for local debugging)

npx @modelcontextprotocol/inspector python server.py

This opens a browser UI where you can call each tool manually and see the raw JSON-RPC request/response — the best way to understand what's actually crossing the wire between client and server.

Deploying to Smithery

1. Push this folder to a public GitHub repo (needs server.py, pyproject.toml, requirements.txt, and smithery.yaml).
2. Go to smithery.ai → New Server → connect your GitHub repo.
3. Smithery reads smithery.yaml to learn how to start the server (python server.py over stdio) and builds/deploys it automatically.
4. Once deployed, anyone can add it to their own MCP client straight from your Smithery listing page — no local setup required on their end.

Notes on how it's built

Built with the official MCP Python SDK using FastMCP, which turns plain Python functions into MCP tools via the @mcp.tool() decorator — the type hints and docstring become the tool's JSON schema and description automatically, which is what the client model reads to decide when and how to call each tool.