MCP 服务器

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.

README

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:

Tool	What it does
`add_todo(title, description)`	Adds a new todo
`list_todos()`	Returns every todo currently saved
`get_todo(todo_id)`	Returns one todo by its ID
`complete_todo(todo_id)`	Marks a todo as completed
`delete_todo(todo_id)`	Removes a todo permanently

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

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