Donetick MCP服务器

](https://pypi.org/project/donetick-mcp-server/) ![Python 3.11+](https://www.python.org/downloads/) ![License: MIT](https://opensource.org/licenses/MIT) ](https://github.com/jason1365/donetick-mcp-server)

一种模型上下文协议（MCP）服务器多尼克家务管理。使Claude和其他兼容MCP的AI助手能够通过速率受限的API与Donetick实例进行交互。

特性

16个MCP工具：完成杂务管理（列表、获取、创建、完成、更新、删除、跳过）、标签组织（列表、创建、更新、移除）、圈子成员信息、用户管理（列出圈子用户、获取用户配置文件）
API全面集成：使用Donetick Full API（/API/v1/），所有端点都正确配置了尾随斜杠
完整的现场支持：所有26个以上的杂务创建字段都在工作，包括频率元数据、滚动时间表、多个受让人、分配策略、通知、标签、优先级、点数、子任务等
一致的现场套管：整个camelCase字段（名称、描述、dueDate、createdBy等）
专业更新工具：使用专用端点更新杂务详细信息、优先级和受让人
JWT身份验证：自动令牌管理，透明刷新
智能缓存：用于get_chore操作的智能缓存（默认为60s 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

克隆存储库:

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

创建 .env 文件:

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

配置环境变量:

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

构建并运行:

   docker-compose build
   docker-compose up -d

选项3:pip安装（用于系统集成）

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

# 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密码（与网络登录相同）

运作原理:

服务器在启动时使用您的凭据登录
JWT令牌已接收并存储在内存中
令牌在过期前自动刷新
无需手动管理令牌

安全:

凭据仅存储在环境变量中或 .env 文件
JWT令牌仅保存在内存中（从不持久化到磁盘）
自动令牌刷新可防止会话过期
所有连接都需要HTTPS

Claude桌面集成

最简单的方法-Claude代码CLI：

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

或者手动编辑配置文件：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json 视窗: %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安装配置

{
  "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 （字符串，可选）：杂务重复的频率-“一次”、“每天”、“每周”、“每月”、“每年”、“基于间隔”（默认值：“一次）
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 （字符串，可选）：分配策略-“最小完成”、“round_robin”、“随机”（默认值：“最小完成度”）

通知参数:

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.完成_码头

将一项杂务标记为已完成。

参数:

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
用户名
显示名称
角色（管理员/成员）
活动状态
积分和兑换积分

示例:

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

配置

环境变量

变量	必填	默认	描述
`DONETICK_BASE_URL`	是	-	您的Donetick实例URL（必须使用HTTPS）
`DONETICK_USERNAME`	是	-	您的Donetick用户名
`DONETICK_PASSWORD`	是	-	您的Donetick密码
`LOG_LEVEL`	否	信息	日志记录级别（调试、信息、警告、错误）
`RATE_LIMIT_PER_SECOND`	否	10.0	每秒请求数限制
`RATE_LIMIT_BURST`	否	10	最大突发大小

速率限制

服务器实现令牌桶速率限制器，以防止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

备注：The tmp/ 目录用于开发过程中的临时测试脚本和分析文件。它被忽略了，没有包含在发布中。

API文档

此服务器使用 Donetick完整API (/api/v1/)通过JWT身份验证。

官方资源

多尼克文件: https://docs.donetick.com/
Donetick GitHub: https://github.com/donetick/donetick

API体系结构

使用的端点:

列出合唱: GET /api/v1/chores/ （需要尾随斜线）
获取Chore: GET /api/v1/chores/{id} （包括子任务）
创建合唱: POST /api/v1/chores/
更新Chore: 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/).这是由客户端自动处理的。

重要说明

已使用完整的API：不是外部API（eAPI）-使用内部完整API
现场套管：始终如一的案例（姓名、描述、到期日期、创建日期）
尾随屠宰：列表端点包括尾随斜线，以便正确路由
认证：JWT Bearer代币，具有自动管理功能
完整的功能支持：所有26个以上的家务创建字段都可用
自动令牌刷新：JWT令牌透明刷新
圆圈范围：所有操作都适用于你的圈子（家庭/团队）
无保费限制：通过完整的API提供的所有功能

故障排除

常见问题

“DONETICK_BASE_URL环境变量是必需的”

确保你的 .env 文件存在并且格式正确
对于Docker：确保在Docker-compose.yml中传递环境变量

“价格有限，正在等待…”

服务器遵守API速率限制
考虑减少 RATE_LIMIT_PER_SECOND 如果这种情况经常发生

“连接被拒绝”或超时错误

验证您的Donetick实例URL是否正确
检查您的Donetick实例是否可访问
确保防火墙规则允许出站连接

“401未经授权”或“凭据无效”

验证您的用户名和密码是否正确
检查您的帐户是否未被锁定或禁用
确保您可以使用相同的凭据登录Donetick web界面
检查环境变量中的拼写错误

工具未在Claude中显示

配置更改后重新启动Claude Desktop
检查Claude Desktop日志是否有错误
验证配置文件路径是否正确

调试

启用调试日志记录：

export LOG_LEVEL=DEBUG

或者在Docker中：

environment:
  - LOG_LEVEL=DEBUG

查看Docker日志：

docker-compose logs -f donetick-mcp

安全

凭证：从不将凭据提交到版本控制（使用 .env 文件）
JWT代币：仅存储在内存中，从不持久化到磁盘
自动令牌刷新：在没有用户干预的情况下防止会话过期
Docker隔离：在容器中以非root用户身份运行
资源限制：内存和CPU限制可防止资源耗尽
输入验证：Pydantic模型验证所有输入
需要HTTPS：服务器对所有Donetick连接强制使用HTTPS

贡献

欢迎投稿！拜托：

分叉存储库
创建要素分支
添加新功能的测试
确保所有测试通过
提交拉取请求

许可证

MIT许可证-有关详细信息，请参阅许可证文件

致谢

多尼克 -开源家务管理
模型上下文协议 -MCP规范
Anthropic -MCP SDK和Claude

支持

问题: https://github.com/jason1365/donetick-mcp-server/issues
多尼克文件: https://docs.donetick.com
MCP文件: https://modelcontextprotocol.io

______________________________________________________________________

内置❤️ Donetick和MCP社区

Donetick MCP Server

快速接入

详细介绍