de en es ja ko ru zh

todo-mcp-server

Name: todo-mcp-server
Author: moazhassan751

by moazhassan751

Overview Schema Source Related Servers Discussions Admin

Python

Hybrid

Todo MCP Server

一个基于 Model Context Protocol (MCP) 构建的健壮、持久化任务管理服务器，使用 Python 和 FastMCP 实现。

概述

Todo MCP Server 为语言模型和 AI 代理提供持久化、有状态的任务管理接口。它基于官方 Python MCP SDK（FastMCP）构建，提供的工具允许 AI 助手直接在其工作流程中创建、跟踪、筛选和完成任务。

状态会持久化到本地的结构化 JSON 存储（tasks.json）中，确保任务数据在服务器重启、客户端重连以及多轮代理会话后依然保留。通信遵循 MCP 规范，通过标准输入/输出（stdio）使用 JSON-RPC 2.0。

Related MCP server: mcpappwrite

架构与数据流

+-------------------------------------------------------------------+
|                        MCP Host / AI Client                       |
|               (Claude Desktop, Cursor, Antigravity)               |
+-------------------------------------------------------------------+
                                  |
                   JSON-RPC 2.0 over stdin / stdout
                                  v
+-------------------------------------------------------------------+
|                       Todo MCP Server                             |
|                                                                   |
|   +-----------------------------------------------------------+   |
|   |                       FastMCP Engine                      |   |
|   |  - Protocol negotiation & schema reflection               |   |
|   |  - Tool dispatch & argument validation (Pydantic/Typing)  |   |
|   +-----------------------------------------------------------+   |
|                                 |                                 |
|   +-----------------------------+-----------------------------+   |
|   |                             |                             |   |
|   v                             v                             v   |
| [ add_task ]             [ list_tasks ]             [ complete_task ]
|   |                             |                             |   |
|   +-----------------------------+-----------------------------+   |
|                                 |                                 |
|                                 v                                 |
|   +-----------------------------------------------------------+   |
|   |                    Storage Controller                     |   |
|   |  - Atomic read/write operations                           |   |
|   |  - Schema serialization with ISO 8601 UTC timestamps      |   |
|   +-----------------------------------------------------------+   |
+-------------------------------------------------------------------+
                                  |
                                  v
+-------------------------------------------------------------------+
|                      Local Storage: tasks.json                    |
+-------------------------------------------------------------------+

工具参考

服务器提供三个不同的工具，用于完整的任务生命周期管理。

1. `add_task`

创建一个新的任务项，并将其追加到持久化存储中。

描述： 向待办列表添加新任务。
参数：
- title（string，必填）：任务描述。长度必须在 1 到 200 个字符之间。
- priority（string，可选）：紧急程度。可接受的值："low"、"medium"、"high"。默认值："medium"。
验证规则：
- 拒绝空字符串或仅含空白字符的字符串。
- 超过 200 个字符的标题会返回错误。
- 不符合要求的优先级值无法通过模式验证。

示例请求：

{
  "title": "Implement integration test suite",
  "priority": "high"
}

示例响应：

Task added!
  ID:       1
  Title:    Implement integration test suite
  Priority: high
  Status:   pending

2. `list_tasks`

检索已保存的任务，并可按完成状态进行可选筛选。

描述： 列出待办列表中的任务，并支持可选的状态筛选。
参数：
- status（string，可选）：筛选条件。可接受的值："all"、"pending"、"done"。默认值："all"。
格式： 返回一个格式化的 ASCII 表格，汇总任务 ID、状态指示符、优先级和标题。

示例请求：

{
  "status": "pending"
}

示例响应：

Tasks (pending) — 2 found:

  ID  Status    Priority Title
————  ————————— ———————— ————————————————————————————————————————
   1  pending   high     Implement integration test suite
   2  pending   medium   Update project documentation

3. `complete_task`

通过任务的唯一整数标识符将现有任务标记为已完成。

描述： 通过任务的数字 ID 将任务标记为已完成。
参数：
- task_id（integer，必填）：分配给任务的唯一数字标识符。
行为：
- 将任务状态更新为 "done"。
- 将 completed_at 字段设置为当前的 ISO 8601 UTC 时间戳。
- 幂等性：如果任务已完成，工具会通知客户端，而不会破坏时间戳。
- 如果 ID 不存在，将返回错误响应，并附上当前有效的 ID 列表。

示例请求：

{
  "task_id": 1
}

示例响应：

Task 1 completed!
  Title:        Implement integration test suite
  Completed at: 2026-08-20T09:46:17.466797+00:00

工具汇总表

工具	用途	参数	返回类型
`add_task`	创建新任务	`title`（str，必填）`priority`（`"low"` \| `"medium"` \| `"high"`，默认值：`"medium"`）	`string`（确认详情）
`list_tasks`	查询已存储的任务	`status`（`"all"` \| `"pending"` \| `"done"`，默认值：`"all"`）	`string`（格式化表格）
`complete_task`	将任务标记为已完成	`task_id`（int，必填）	`string`（完成状态与时间戳）

数据模型与持久化

任务记录以 UTF-8 编码的 JSON 数组形式序列化。默认情况下，记录存储在当前工作目录的 tasks.json 中。存储文件路径可通过 TODO_FILE 环境变量自定义。

模式定义

[
  {
    "id": 1,
    "title": "Implement integration test suite",
    "priority": "high",
    "status": "done",
    "created_at": "2026-08-20T09:46:17.362387+00:00",
    "completed_at": "2026-08-20T09:46:17.466797+00:00"
  },
  {
    "id": 2,
    "title": "Update project documentation",
    "priority": "medium",
    "status": "pending",
    "created_at": "2026-08-20T09:46:17.384689+00:00",
    "completed_at": null
  }
]

字段说明

id（integer）：自增的正整数标识符。
title（string）：任务描述字符串（1-200 个字符）。
priority（string）：紧急程度分类（"low"、"medium"、"high"）。
status（string）：生命周期阶段（"pending" 或 "done"）。
created_at（string）：创建时记录的 ISO 8601 格式 UTC 时间戳。
completed_at（string | null）：完成时记录的 ISO 8601 格式 UTC 时间戳。

环境要求

Python：3.10 或更高版本
依赖项：
- mcp[cli]>=1.28,<2

安装与设置

1. 克隆仓库

git clone https://github.com/moazhassan751/mcp-todo-server.git
cd mcp-todo-server

2. 创建虚拟环境

# Linux/macOS
python3 -m venv .venv
source .venv/bin/activate

# Windows
python -m venv .venv
.venv\Scripts\activate

3. 安装依赖

pip install -r requirements.txt

执行模式

标准执行（stdio）

直接运行服务器，用于生产环境或 MCP 主机集成：

python server.py

开发者检查（MCP Inspector）

MCP Inspector 提供基于浏览器的交互式界面，用于测试工具、检查模式以及模拟请求：

mcp dev server.py

检查器启动后将提供一个本地界面 URL（通常为 http://localhost:6274）。

客户端集成指南

要将 Todo MCP Server 连接到您偏好的 AI 环境，请在客户端的 MCP 配置文件中配置该服务器。

Claude Desktop

编辑您的 Claude Desktop 配置文件：

macOS：~/Library/Application Support/Claude/claude_desktop_config.json
Windows：%APPDATA%\Claude\claude_desktop_config.json

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

Cursor

将以下内容添加到项目或全局目录中的 .cursor/mcp.json：

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

Antigravity IDE

将以下内容添加到工作区中的 .agents/mcp_config.json：

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

测试与验证

该仓库包含全面的自动化测试脚本：

标准测试套件

测试基本的工具调用、参数验证和输出格式：

python test_server.py

多会话审计测试

模拟独立的客户端连接，在会话之间重启服务器进程，并验证持久化存储是否正确保留状态：

python audit_test.py

项目结构

mcp-todo-server/
├── server.py           # Core MCP server definition and tool implementations
├── test_server.py      # Automated stdio protocol unit tests
├── audit_test.py       # Multi-session persistence and edge-case verification
├── requirements.txt    # Package dependencies
├── .gitignore          # Version control ignore definitions
└── README.md           # Technical documentation and integration reference

许可证

本项目是开源的，以 MIT 许可证发布。

This server cannot be deployed

Pay for results, not tokens.Fund a bounty. Let AI agents compete and collaborate to solve your problems.agentbounties.appAd

Maintenance

ActivitySlowing

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

acme-todo
com.ritzademo
An MCP server for a simple todo list
Developer Tools App Automation
2
Todo MCP A
io.github.AnkitPat
Create, list, and complete todo items through MCP.
Project Management Workplace & Productivity
1
Done Bear A
com.donebear
Local-first task manager: create, edit, and complete tasks, projects, and checklists via MCP.
Project Management App Automation
171
mcpOAuth
net.todoist
Official Todoist MCP server for AI assistants to manage tasks, projects, and workflows.
App Automation Workplace & Productivity Project Management
2

Related MCP Servers

MCP Todo Server
Project Management Developer Tools
costaadiego1989
A
license
Not graded
quality
D
maintenance
A CRUD todo list server that exposes tools to create, list, and conclude tasks, compatible with any MCP host.
Updated 3 months ago (2026-07-07 15:54 UTC)
7 npm
MIT
mcpappwrite
Cloud Platforms Project Management
sirishdasari
F
license
Not graded
quality
B
maintenance
A minimal Python MCP Todo server backed by Appwrite Cloud, providing tools to add, list, get, update, complete, and delete tasks.
Updated a month ago (2026-08-31 12:15 UTC)
-
MCP Todo Server (TypeScript)
Project Management Workplace & Productivity
MauricioChaves00
A
license
B
quality
C
maintenance
A basic MCP server for managing a todo list stored in a local JSON file, enabling task creation, completion, listing, and daily summary generation.
Updated 2 months ago (2026-08-17 21:58 UTC)
2
7 npm
MIT
Todo List MCP Server
App Automation Project Management
exemuneeb
F
license
Not graded
quality
C
maintenance
A simple MCP server that turns a JSON file into a todo list, letting users add, list, complete, delete, and clear tasks through natural language in MCP-compatible clients.
Updated 2 months ago (2026-08-19 19:59 UTC)
-

Todo MCP Server

概述

架构与数据流

工具参考

1. add_task

2. list_tasks

3. complete_task

工具汇总表

数据模型与持久化

模式定义

字段说明

环境要求

安装与设置

1. 克隆仓库

2. 创建虚拟环境

3. 安装依赖

执行模式

标准执行（stdio）

开发者检查（MCP Inspector）

客户端集成指南

Claude Desktop

Cursor

Antigravity IDE

测试与验证

标准测试套件

多会话审计测试

项目结构

许可证

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

MCP Todo Server

mcpappwrite

MCP Todo Server (TypeScript)

Todo List MCP Server

1. `add_task`

2. `list_tasks`

3. `complete_task`