Donetick MCP 服务器

一个用于 Donetick 家务管理的模型上下文协议（MCP）服务器。使 Claude 及其他兼容 MCP 的 AI 助手能够通过限速 API 与您的 Donetick 实例交互。

功能特点

• 16 个 MCP 工具：完整的家务管理（列出、获取、创建、完成、更新、删除、跳过）、标签组织（列出、创建、更新、删除）、圈子成员信息、用户管理（列出圈子用户、获取用户资料）

• 完整的 API 集成：使用 Donetick 完整 API（/api/v1/），所有端点均已正确配置，包含尾部斜杠

• 全面的字段支持：支持所有 26 个以上的家务创建字段，包括频率元数据、滚动计划、多指派人、分配策略、通知、标签、优先级、积分、子任务等

• 一致的字段命名：全程使用 camelCase 字段（name、description、dueDate、createdBy 等）

• 专门的更新工具：通过专用端点更新家务详情、优先级和指派人

• JWT 认证：自动令牌管理，透明刷新

• 智能缓存：对 get_chore 操作进行智能缓存（默认 60 秒 TTL）

• 速率限制：令牌桶算法防止 API 超载

• 重试逻辑：指数退避加抖动，实现弹性操作

• 异步/等待：使用 httpx 的非阻塞操作

• 输入验证：带清理功能的 Pydantic 字段验证器

• 安全强化：强制 HTTPS、日志清理、安全错误消息、JWT 令牌安全

• Docker 支持：遵循安全最佳实践的容器化部署

• 全面测试：模拟单元/集成测试 + 基于 pytest 的实时 API 测试框架

• 类型安全：用于请求/响应验证的 Pydantic 模型

快速开始

最简单的安装方式（Claude Code CLI）：

claude mcp add donetick uvx donetick-mcp-server@latest

然后根据提示配置您的 Donetick 凭据。

或者使用 uvx 手动安装：

# Install uv (one-time setup)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Add to Claude Desktop config
# ~/.config/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "donetick": {
      "command": "uvx",
      "args": ["--refresh", "donetick-mcp-server"],
      "env": {
        "DONETICK_BASE_URL": "https://your-instance.com",
        "DONETICK_USERNAME": "your_username",
        "DONETICK_PASSWORD": "your_password"
      }
    }
  }
}

优势：

• ✅ 无需安装 - 直接从 PyPI 运行

• ✅ 使用 --refresh 标志自动更新

• ✅ 隔离环境 - 无冲突

• ✅ 适用于 Windows、macOS、Linux

前提条件

• Donetick 实例（自托管或云端）

• Donetick 账户凭据（用户名和密码）

• 对于 uvx 方式： 已安装 uv（参见快速开始）

• 对于其他方式： Python 3.11 或更高版本

安装

方式 1：uvx（推荐 - 无需安装）

参见上面的快速开始。

--refresh 标志确保在 Claude Desktop 重启时始终获取最新版本。

方式 2：Docker

1. 克隆仓库：

   git clone https://github.com/jason1365/donetick-mcp-server.git
   cd donetick-mcp-server

2. 创建 .env 文件：

   cp .env.example .env
   # Edit .env with your configuration

3. 配置环境变量：

   DONETICK_BASE_URL=https://your-instance.com
   DONETICK_USERNAME=your_username
   DONETICK_PASSWORD=your_password
   LOG_LEVEL=INFO

4. 构建并运行：

   docker-compose build
   docker-compose up -d

方式 3：pip install（用于系统集成）

如果希望全局安装或在虚拟环境中安装：

# Install from PyPI
pip install donetick-mcp-server

# Or install for development
git clone https://github.com/jason1365/donetick-mcp-server.git
cd donetick-mcp-server
pip install -e .

# Run the server
donetick-mcp-server
# Or: python -m donetick_mcp.server

然后配置 Claude Desktop 使用已安装的命令：

{
  "mcpServers": {
    "donetick": {
      "command": "donetick-mcp-server",
      "env": {
        "DONETICK_BASE_URL": "https://your-instance.com",
        "DONETICK_USERNAME": "your_username",
        "DONETICK_PASSWORD": "your_password"
      }
    }
  }
}

认证

MCP 服务器使用基于 JWT 的认证，使用您的 Donetick 凭据。

所需信息：

• 您的 Donetick 用户名（与网页登录相同）

• 您的 Donetick 密码（与网页登录相同）

工作原理：

1. 服务器启动时使用您的凭据登录

2. JWT 令牌接收并存储在内存中

3. 令牌在到期前自动刷新

4. 无需手动管理令牌

安全性：

• 凭据仅存储在环境变量或 .env 文件中

• JWT 令牌仅保存在内存中（从不持久化到磁盘）

• 自动令牌刷新防止会话过期

• 所有连接要求使用 HTTPS

Claude Desktop 集成

最简单的方法 - Claude Code CLI：

claude mcp add donetick uvx donetick-mcp-server@latest

或者手动编辑配置文件：

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

uvx 配置（推荐）

{
  "mcpServers": {
    "donetick": {
      "command": "uvx",
      "args": ["--refresh", "donetick-mcp-server"],
      "env": {
        "DONETICK_BASE_URL": "https://your-instance.com",
        "DONETICK_USERNAME": "your_username",
        "DONETICK_PASSWORD": "your_password"
      }
    }
  }
}

注意： --refresh 标志会自动更新到最新版本。

Docker 配置

{
  "mcpServers": {
    "donetick": {
      "command": "docker",
      "args": [
        "exec",
        "-i",
        "donetick-mcp-server",
        "python",
        "-m",
        "donetick_mcp.server"
      ]
    }
  }
}

pip install 配置

{
  "mcpServers": {
    "donetick": {
      "command": "donetick-mcp-server",
      "env": {
        "DONETICK_BASE_URL": "https://your-instance.com",
        "DONETICK_USERNAME": "your_username",
        "DONETICK_PASSWORD": "your_password"
      }
    }
  }
}

更新配置后，重启 Claude Desktop。

可用工具

1. list_chores

列出所有家务，可进行筛选。

参数：

• filter_active（布尔值，可选）：按活动状态筛选

• assigned_to_user_id（整数，可选）：按分配的用户 ID 筛选

示例：

List all active chores assigned to me

2. get_chore

按 ID 获取特定家务的详细信息。

参数：

• chore_id（整数，必填）：家务 ID

示例：

Show me details of chore 123

3. create_chore

创建新家务，支持完整配置。

基本参数：

• name（字符串，必填）：家务名称（1-200 个字符）

• description（字符串，可选）：家务描述（最多 5000 个字符）

• due_date（字符串，可选）：到期日期，格式为 YYYY-MM-DD 或 RFC3339

• created_by（整数，可选）：创建者用户 ID

重复/频率参数：

• frequency_type（字符串，可选）：家务重复频率 - "once"（一次）、"daily"（每天）、"weekly"（每周）、"monthly"（每月）、"yearly"（每年）、"interval_based"（基于间隔），默认："once"

• frequency（整数，可选）：频率倍数，例如 1=每周，2=每两周，默认：1

• frequency_metadata（对象，可选）：额外的频率配置，如 {"days": [1,3,5], "time": "09:00"}

• is_rolling（布尔值，可选）：滚动计划（下次到期基于完成时间）还是固定计划，默认：false

用户分配参数：

• assigned_to（整数，可选）：主要分配的用户 ID

• assignees（数组，可选）：多个指派人，格式为 [{"userId": 1}, {"userId": 2}]

• assign_strategy（字符串，可选）：分配策略 - "least_completed"（最少完成）、"round_robin"（轮询）、"random"（随机），默认："least_completed"

通知参数：

• notification（布尔值，可选）：启用通知，默认：false

• nagging（布尔值，可选）：启用提醒/催促通知，默认：false

• predue（布尔值，可选）：启用到期前通知，默认：false

组织参数：

• priority（整数，可选）：优先级 1-5（1 最低，5 最高）

• labels（数组，可选）：标签，如 ["cleaning", "outdoor"]

状态参数：

• is_active（布尔值，可选）：活动状态 - 非活动家务将被隐藏，默认：true

• is_private（布尔值，可选）：私人家务，仅创建者可见，默认：false

游戏化参数：

• points（整数，可选）：完成时奖励的积分

高级参数：

• sub_tasks（数组，可选）：子任务/检查清单项

示例：

Create a simple one-time chore:
Create a chore called "Take out trash" due on 2025-11-10

Create a recurring chore with notifications:
Create a weekly chore "Clean kitchen" every Monday at 9am with priority 4,
enable nagging notifications, and assign it to user 1

Create an advanced chore:
Create a chore "Grocery shopping" that repeats weekly on Mondays and Wednesdays,
assign to users 1 and 2 using round robin strategy, with priority 3,
labels "shopping" and "outdoor", and award 10 points

4. complete_chore

将家务标记为完成。

参数：

• chore_id（整数，必填）：家务 ID

• completed_by（整数，可选）：完成此任务的用户 ID

示例：

Mark chore 123 as complete

5. delete_chore

永久删除家务。只有创建者可以删除。

参数：

• chore_id（整数，必填）：家务 ID

示例：

Delete chore 123

6. get_circle_members

获取圈子中的所有成员（家庭/团队）。显示您可以分配家务的对象。

参数：无

返回：

• 用户 ID

• 用户名

• 显示名称

• 角色（admin/member）

• 活动状态

• 积分和已兑换积分

示例：

Show me who's in my household
Who can I assign chores to?
List all circle members

配置

环境变量

速率限制

服务器实现了令牌桶速率限制器，防止 API 超载：

• 默认：每秒 10 个请求，突发容量为 10

• 保守：起始保守，可根据您的 Donetick 实例增加

• 尊重 429：当 API 限制速率时自动退避

重试逻辑

• 指数退避加抖动，处理瞬时故障

• 大多数操作最多重试 3 次

• 智能重试：仅对 5xx 错误和 429（速率限制）重试

• 不对 4xx 重试：客户端错误立即失败（429 除外）

开发

运行测试

模拟测试（快速，无需 Donetick 实例）：

# Install dev dependencies
pip install -e ".[dev]"

# Run all tests (unit + integration with mocks)
pytest

# Run with coverage
pytest --cov=donetick_mcp --cov-report=html

# Run specific test file
pytest tests/test_client.py
pytest tests/test_server.py

# Run with verbose output
pytest -v

实时 API 测试（需要 Donetick 实例）：

# Create .env file with credentials (see Configuration section)
# Then run live API integration tests
pytest tests/integration/test_live_api.py -v

# Skip live tests
pytest -m "not live_api"

# Run only live tests
pytest -m live_api

测试覆盖率详情：

• 模拟测试验证逻辑、重试行为、速率限制、错误处理

• 实时 API 测试验证端点路由、字段命名兼容性、响应格式

• 全面覆盖确保 API 客户端可靠性和 MCP 工具正确性

项目结构

donetick-mcp-server/
├── src/donetick_mcp/
│   ├── __init__.py
│   ├── server.py          # MCP server implementation
│   ├── client.py           # Donetick API client
│   ├── models.py           # Pydantic data models
│   └── config.py           # Configuration management
├── tests/
│   ├── test_client.py      # API client tests
│   └── test_server.py      # MCP server tests
├── tmp/                    # Temporary files (gitignored)
├── Dockerfile
├── docker-compose.yml
├── pyproject.toml
└── README.md

注意：tmp/ 目录用于开发期间的临时测试脚本和分析文件。它被 gitignore 忽略，不包含在发布版本中。

API 文档

此服务器使用 Donetick 完整 API（/api/v1/）和 JWT 认证。

官方资源

• Donetick 文档：https://docs.donetick.com/

• Donetick GitHub：https://github.com/donetick/donetick

API 架构

使用的端点：

• 列出家务：GET /api/v1/chores/（需要尾部斜杠）

• 获取家务：GET /api/v1/chores/{id}（包含子任务）

• 创建家务：POST /api/v1/chores/

• 更新家务：PUT /api/v1/chores/{id}（名称、描述、nextDueDate）

• 更新优先级：PUT /api/v1/chores/{id}/priority

• 更新指派人：PUT /api/v1/chores/{id}/assignee

• 跳过家务：PUT /api/v1/chores/{id}/skip

• 完成家务：POST /api/v1/chores/{id}/do

• 删除家务：DELETE /api/v1/chores/{id}

• 获取成员：GET /api/v1/circles/members/（需要尾部斜杠）

重要提示：列表端点需要尾部斜杠（/api/v1/chores/、/api/v1/circles/members/）。客户端会自动处理。

重要说明

1. 使用完整 API：不是外部 API（eAPI） - 使用内部完整 API

2. 字段命名：全程使用一致的 camelCase（name、description、dueDate、createdBy）

3. 尾部斜杠：列表端点包含尾部斜杠以实现正确路由

4. 认证：JWT Bearer 令牌，自动管理

5. 完整功能支持：支持所有 26 个以上的家务创建字段

6. 自动令牌刷新：JWT 令牌透明刷新

7. 圈子范围：所有操作限定在您的圈子（家庭/团队）内

8. 无高级限制：通过完整 API 可使用所有功能

故障排除

常见问题

"DONETICK_BASE_URL environment variable is required"

• 确保您的 .env 文件存在且格式正确

• 对于 Docker：确保环境变量在 docker-compose.yml 中传递

"Rate limited, waiting..."

• 服务器正在遵守 API 速率限制

• 如果频繁发生，请考虑降低 RATE_LIMIT_PER_SECOND

"Connection refused" 或超时错误

• 验证您的 Donetick 实例 URL 是否正确

• 检查您的 Donetick 实例是否可访问

• 确保防火墙规则允许出站连接

"401 未授权" 或 "无效凭据"

• 确认你的用户名和密码正确

• 检查你的账户未被锁定或禁用

• 确保你能使用相同的凭据登录 Donetick 网页界面

• 检查环境变量中是否有拼写错误

工具未在 Claude 中显示

• 配置更改后重启 Claude Desktop

• 检查 Claude Desktop 日志中的错误

• 验证配置文件路径是否正确

调试

启用调试日志：

export LOG_LEVEL=DEBUG

或在 Docker 中：

environment:
  - LOG_LEVEL=DEBUG

查看 Docker 日志：

docker-compose logs -f donetick-mcp

安全

• 凭据：切勿将凭据提交到版本控制（使用 .env 文件）

• JWT Tokens：仅存储在内存中，从不持久化到磁盘

• 自动令牌刷新：无需用户干预即可防止会话过期

• Docker 隔离：以非 root 用户身份在容器中运行

• 资源限制：内存和 CPU 限制防止资源耗尽

• 输入验证：Pydantic 模型验证所有输入

• 要求 HTTPS：服务器对所有 Donetick 连接强制使用 HTTPS

贡献

欢迎贡献！请按以下步骤操作：

1. Fork 仓库

2. 创建功能分支

3. 为新功能添加测试

4. 确保所有测试通过

5. 提交 Pull Request

许可证

MIT 许可证 - 详见 LICENSE 文件

致谢

• Donetick - 开源家务管理

• Model Context Protocol - MCP 规范

• Anthropic - MCP SDK 和 Claude

支持

• 问题：https://github.com/jason1365/donetick-mcp-server/issues

• Donetick 文档：https://docs.donetick.com

• MCP 文档：https://modelcontextprotocol.io

为 Donetick 和 MCP 社区用 ❤️ 构建