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:

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

Related MCP server: MCP Todo Server

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.