Todo List MCP Server

一个简单、适合初学者的 Model Context Protocol (MCP) 服务器，使用 Python 编写。 它让任何 MCP 兼容的 AI 客户端（如 Claude Desktop）都能通过五个工具管理你计算机上的待办清单：添加、查看、按 ID 获取、完成和删除。

使用官方 MCP Python SDK（mcp[cli]）及其高层 FastMCP 接口构建。 数据以纯 JSON 文件形式存储在本地——无需数据库。

1. 这个项目做什么

这个 MCP 服务器向任何连接的 AI 客户端提供 5 个工具：

所有数据都存放在 todos.json 中，该文件在你第一次添加待办事项时自动创建。

Related MCP server: Task MCP Server

2. 项目结构

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. 安装

先决条件

• Python 3.10 或更高版本

• pip（随 Python 一起提供）

步骤

# 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. 运行服务器

选项 A — MCP Inspector（推荐用于测试）：

mcp dev server.py

这会打开一个基于浏览器的界面，你可以手动调用每个工具并查看 JSON 响应。

选项 B — 安装到 Claude Desktop：

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

这会注册服务器，使 Claude Desktop 自动启动它。

选项 C — 直接运行：

python server.py

5. 测试 / 示例提示（在 Claude Desktop 中）

在 Claude Desktop 中连接后，尝试：

• "添加一个待办事项：购买日用品，描述为牛奶、鸡蛋和面包"

• "显示我所有的待办事项"

• "获取 ID 为 1 的待办事项"

• "将待办事项 1 标记为已完成"

• "删除待办事项 2"

6. 架构

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

客户端从不直接接触 JSON 文件——它只调用工具，由服务器决定数据如何存储。这种分离是 MCP 的核心设计理念：客户端不需要知道工具内部如何工作，只需要知道它做什么。

7. 学习成果

通过这个项目，我学到了：

• Model Context Protocol (MCP) 是什么，以及它如何标准化 LLM 的工具访问

• MCP 服务器、客户端以及工具/资源/提示之间的区别

• 如何使用官方 Python SDK 的 FastMCP 接口，从普通的 Python 函数和类型提示快速构建工具

• 如何使用 JSON 文件在本地存储和管理数据

• 如何在 Claude Desktop 中连接和测试自定义 MCP 服务器

• 如何在 GitHub 上打包、编写文档并发布一个小型 Python 项目

• 如何将 MCP 服务器发布到像 Smithery 这样的市场的基础知识

许可证

MIT — 可自由使用、修改和分享。

作者

Haseeba Yasin

如果你觉得这个项目有帮助，请随意 ⭐ 这个仓库。