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

Push this folder to a public GitHub repo (needs server.py, pyproject.toml, requirements.txt, and smithery.yaml).
Go to smithery.ai → New Server → connect your GitHub repo.
Smithery reads smithery.yaml to learn how to start the server (python server.py over stdio) and builds/deploys it automatically.
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.