Donetick MCP Server

Donetick の家事管理のための Model Context Protocol (MCP) サーバーです。Claude やその他の MCP 互換 AI アシスタントが、レート制限付き API を通じて Donetick インスタンスと対話できるようにします。

機能

• 16 個の MCP ツール: 家事の完全管理（一覧表示、取得、作成、完了、更新、削除、スキップ）、ラベル整理（一覧表示、作成、更新、削除）、サークルメンバー情報、ユーザー管理（サークルユーザーの一覧表示、ユーザープロフィールの取得）

• 完全な API 統合: Donetick Full API (/api/v1/) を使用し、すべてのエンドポイントが末尾スラッシュ付きで適切に設定されています

• 完全なフィールドサポート: 頻度メタデータ、ローリングスケジュール、複数担当者、割り当て戦略、通知、ラベル、優先度、ポイント、サブタスクなど、26 以上の家事作成フィールドがすべて動作します

• 一貫したフィールドのケーシング: 全体で camelCase フィールド（name、description、dueDate、createdBy など）

• 専用の更新ツール: 専用エンドポイントを使用して家事の詳細、優先度、担当者を更新

• JWT 認証: 透過的なリフレッシュによる自動トークン管理

• スマートキャッシング: get_chore 操作のインテリジェントなキャッシュ（デフォルトで 60 秒 TTL）

• レート制限: トークンバケットアルゴリズムによる API 過負荷防止

• リトライロジック: ジッター付き指数バックオフによる回復力のある操作

• Async/Await: 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 サーバーは、Donetick の認証情報を使用した JWT ベースの認証を使用します。

必要なもの:

• Donetick のユーザー名（Web ログインと同じ）

• Donetick のパスワード（Web ログインと同じ）

仕組み:

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 の過負荷を防ぎます:

• デフォルト: 1 秒あたり 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 ドキュメント

このサーバーは、JWT 認証を使用する Donetick Full API（/api/v1/）を使用します。

公式リソース

• 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}（name、description、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. Full API を使用: 外部 API（eAPI）ではなく、内部の Full API を使用

2. フィールドケーシング: 全体で一貫した camelCase（name、description、dueDate、createdBy）

3. 末尾スラッシュ: 一覧エンドポイントには適切なルーティングのため末尾スラッシュを含む

4. 認証: 自動管理付き JWT Bearer トークン

5. 完全な機能サポート: 26 以上の家事作成フィールドがすべて利用可能

6. 自動トークンリフレッシュ: JWT トークンは透過的にリフレッシュ

7. サークルスコープ: すべての操作はサークル（世帯/チーム）にスコープされる

8. プレミアム制限なし: Full 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を強制

コントリビューション

コントリビューションを歓迎します！以下の手順に従ってください：

1. リポジトリをフォーク

2. 機能ブランチを作成

3. 新しい機能のテストを追加

4. すべてのテストが合格することを確認

5. プルリクエストを送信

ライセンス

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コミュニティのために❤️を込めて作られました