mcp-task-manager

一个本地任务管理器，通过 Anthropic 的 Model Context Protocol 接入 Claude Desktop。没有 UI，没有后端服务——只有一个 Python 进程和一个 SQLite 文件。你通过与 Claude 对话来管理任务。

“创建一个高优先级的任务来修复身份验证错误，截止日期为周五，标记为后端。” → 任务已创建。 “我今天应该关注什么？” → 返回逾期 + 紧急 + 高优先级的任务。 “将任务 3 标记为已完成并给我一个摘要。” → 已完成 + 统计信息。

技术栈： Python 3.11+ · FastMCP · SQLite · Pydantic v2 状态： 本地运行正常，已实现 9 个工具

为什么选择这个项目

构建此项目是为了端到端学习 MCP：服务器生命周期、工具注册、stdio 传输，以及 Claude 如何从自然语言请求中选择工具。这是一个小巧但完整的示例——你可以将其扩展为工作中实际的内部工具。

工作原理

MCP 服务器作为本地子进程运行。Claude Desktop 使用 JSON-RPC 通过 stdio 与服务器通信。当你输入消息时，Claude 会：

选择符合请求的已注册工具
从你的自然语言中填充参数
调用工具，获取结构化数据（Pydantic 模型）
用简单的英语向你总结结果

Claude Desktop  ──── JSON-RPC (stdio) ────  server.py  (FastMCP)
                                                │
                                         TaskRepository
                                                │
                                           tasks.db  (SQLite)

工具

工具	功能
`create_task`	创建一个包含标题、描述、优先级、截止日期、标签的任务
`list_tasks`	列出任务，可选择按状态和/或优先级进行筛选
`get_task`	通过 ID 获取单个任务
`update_task`	更新任何字段（标题、描述、优先级、状态、截止日期、标签）
`complete_task`	快捷方式——标记为 `completed`（已完成）
`delete_task`	通过 ID 删除任务
`search_tasks`	在标题、描述和标签中进行子字符串搜索
`get_summary`	按状态和优先级计数 + 逾期计数
`plan_day`	今日优先关注列表（逾期 + 紧急 + 高优先级）

优先级：low（低） · medium（中） · high（高） · urgent（紧急）状态：pending（待办） · in_progress（进行中） · completed（已完成） · cancelled（已取消）

项目结构

mcp-task-manager/
├── server.py           # FastMCP entry point, tool registration, lifespan
├── core/
│   ├── models.py       # Pydantic models + enums (Task, TaskCreate, TaskUpdate, TaskSummary)
│   └── repository.py   # SQLite DAO — CRUD, search, summary
├── tools/
│   └── __init__.py     # 9 MCP tool functions (thin layer over repository)
├── pyproject.toml
└── .env.example

三层架构，各司其职：

tools/ — 面向 MCP 的接口层。每个函数都有一个文档字符串，Claude 通过读取它来了解何时以及如何调用它。
core/repository.py — SQLite 访问层。原始 SQL，在 status、priority、due_date 上建立了索引。
core/models.py — 验证、序列化、枚举。

设置

要求： Python 3.11+，Claude Desktop。

git clone https://github.com/soltyDude/mcp-task-manager.git
cd mcp-task-manager

python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate

pip install -e .
cp .env.example .env

连接到 Claude Desktop

打开你的 Claude Desktop 配置文件：

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

添加服务器：

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

重启 Claude Desktop。工具将出现在 🔌 图标下。

配置

.env 支持两个变量：

DATABASE_PATH=tasks.db       # where SQLite stores data
SERVER_NAME=mcp-task-manager # name shown in Claude Desktop

示例会话

You:    Add a task: refactor the auth filter, high priority, due tomorrow, tags: backend, security

Claude: Created task #1 — "Refactor the auth filter" (high, due 2025-04-19, tags: backend, security)

You:    What's my plan for today?

Claude: 📅 Day plan for 2025-04-18
        🔥 FOCUS (urgent + high priority)
          [1] [HIGH] Refactor the auth filter  #backend #security
        📊 Total: 1 | In progress: 0 | Overdue: 0

You:    Mark it in progress and show a summary

Claude: Task #1 updated — status: in_progress.
        📊 Total: 1 | Pending: 0 | In progress: 1 | Completed: 0 | Overdue: 0

设计说明

如果你是以审阅者的身份阅读本文，以下是一些值得注意的选择：

生命周期作用域的存储库。 TaskRepository 在 FastMCP 的 lifespan 上下文管理器中构建一次，并通过 ctx.request_context.lifespan_context 注入。工具保持无状态；连接细节不会泄露到工具代码中。
使用枚举而非魔法字符串。 Priority 和 TaskStatus 是 str 枚举——在输入时由 Pydantic 验证，在 SQLite 中存储为字符串，在中间的所有地方都进行了类型化。
将标签作为 JSON 存储在 TEXT 列中。 对于 SQLite 来说很务实——本地工具不需要连接表。搜索使用 LIKE 对序列化的 JSON 进行操作。如果将来迁移到 Postgres，它将变为 text[] 或真正的标签表。
对热点路径建立索引。 status、priority、due_date——这是每个过滤器都会命中的三列。
plan_day 去重。 紧急和高优先级查询可能与逾期列表重叠，因此最终的关注列表是使用 seen 集合构建的。

限制 / 后续步骤

暂无测试——计划：使用内存中的 SQLite 固定装置为存储库层编写 pytest。
没有循环任务。
搜索基于 LIKE；对于更大的数据集，升级到 SQLite FTS5 会更好。
设计为单用户、单机使用。多用户意味着将 SQLite 换成 Postgres 并添加用户列。

许可证

MIT

mcp-task-manager

mcp-task-manager

为什么选择这个项目

工作原理

工具

项目结构

设置

连接到 Claude Desktop

配置

示例会话

设计说明

限制 / 后续步骤

许可证

Resources

Looking for Admin?

Latest Blog Posts

MCP directory API