clickup-mcp-server: A ClickUp MCP Server

clickup-mcp-server：ClickUp MCP サーバー

概要

ClickUp API との連携と自動化のための Model Context Protocol サーバーです。このサーバーは、AI システムが ClickUp のタスク、リスト、スペースを読み取り、作成、更新するためのツールを提供します。

この MCP サーバーにより、Claude などの AI ツールが ClickUp ワークスペースを操作できるようになり、タスク管理、プロジェクト計画、その他のワークフローの自動化に役立ちます。

機能

この MCP サーバーは ClickUp との包括的な連携を提供し、次の機能を備えています。

タスク管理

• タスクの作成、更新、削除
• リストやボード間でのタスクの移動と複製
• 期限、優先度、タグなどのタスクプロパティの設定
• サブタスクの作成、表示、管理
• タスクへのコメントや添付ファイルの追加
• 単一タスクと一括タスクの両方の操作に対応
• ステータスによるタスクのグループ化とフィルタリング

ワークスペースの整理

• ワークスペース、スペース、フォルダー、リストの移動と管理
• スペースとフォルダーの作成、更新、削除
• スペースやフォルダー内でのリストの整理
• ワークスペース階層全体の表示
• パス表記を使ったワークスペース内の効率的な移動
• スペース内またはフォルダー内でのリストの作成

書式設定と表示

• タスクの説明とコメントでの完全な Markdown サポート
• ClickUp で適切に表示するための HTML 変換
• タスクの詳細、リスト、階層の書式付き表示
• 複雑なプロジェクト構造の見やすい表示

開発者向け機能

• 包括的なエラー処理と検証
• 明確で一貫性のある API レスポンス
• すべてのツールの詳細なドキュメント
• Claude やその他の AI システムとの簡単な連携

ツール

このサーバーは、ClickUp と連携するために次のツールを提供します。

ワークスペース／チームのツール

1. get_workspaces

   • すべてのワークスペース／チームを取得します
   • 入力：なし
   • 戻り値：ID と名前を含むワークスペースのリスト

2. navigate_workspace

   • パス表記を使ってワークスペース階層内を移動します
   • 入力：
     • path（string）：ワークスペース階層内のパス（team_id/space_name/folder_name/list_name）
   • 戻り値：対象エンティティの詳細と完全なパス

スペースのツール

3. get_spaces

   • ワークスペース内のすべてのスペースを取得します
   • 入力：
     • workspace_id（string）：ワークスペース／チームの ID
   • 戻り値：ID と名前を含むスペースのリスト

4. create_space

   • ワークスペース内に新しいスペースを作成します
   • 入力：
     • workspace_id（string）：ワークスペース／チームの ID
     • name（string）：新しいスペースの名前
   • 戻り値：作成したスペースの詳細

5. get_space_hierarchy

   • フォルダーとリストを含むスペースの完全な階層を取得します
   • 入力：
     • space_id（string）：スペースの ID
   • 戻り値：スペースの完全な階層構造

フォルダーのツール

6. get_folders

   • スペース内のすべてのフォルダーを取得します
   • 入力：
     • space_id（string）：スペースの ID
   • 戻り値：ID と名前を含むフォルダーのリスト

7. create_folder

   • スペース内に新しいフォルダーを作成します
   • 入力：
     • space_id（string）：スペースの ID
     • name（string）：新しいフォルダーの名前
   • 戻り値：作成したフォルダーの詳細

8. update_folder

   • フォルダーの名前を更新します
   • 入力：
     • folder_id（string）：更新するフォルダーの ID
     • name（string）：フォルダーの新しい名前
   • 戻り値：更新後のフォルダーの詳細

9. delete_folder

   • フォルダーを削除します
   • 入力：
     • folder_id（string）：削除するフォルダーの ID
   • 戻り値：削除の確認

リスト／ボードツール

10. get_lists

    • スペース内のすべてのリスト／ボードを取得します
    • 入力：
      • space_id (string)：スペースの ID
    • 戻り値：ID と名前を含むリスト／ボードの一覧

11. create_list

    • スペースまたはフォルダーに新しいリスト／ボードを作成します
    • 入力：
      • space_id (string)：スペースの ID
      • name (string)：新しいリスト／ボードの名前
      • folder_id (string, optional)：フォルダーの ID（フォルダー内にリストを作成する場合）
    • 戻り値：作成したリスト／ボードの詳細

12. organize_lists

    • リストを場所（スペース内またはフォルダー内）ごとに整理します
    • 入力：
      • space_id (string)：スペースの ID
      • folder_id (string, optional)：特定のフォルダーの ID
    • 戻り値：格納先のフォルダーごとに整理されたリスト

タスクツール

13. get_tasks

• リスト／ボード内のすべてのタスクを取得します
• 入力：
  • list_id (string)：リスト／ボードの ID
• 戻り値：ID、名前、その他の詳細を含むタスクの一覧

14. get_tasks_by_status

    • リスト／ボード内で指定したステータスのタスクを取得します
    • 入力：
      • list_id (string)：リスト／ボードの ID
      • status (string)：タスクの絞り込みに使用するステータス
    • 戻り値：指定したステータスのタスク一覧

15. create_task

    • リスト／ボードに新しいタスクを作成します
    • 入力：
      • list_id (string)：リスト／ボードの ID
      • name (string)：タスクの名前
      • description (string, optional)：タスクの説明
      • priority (number, optional)：タスクの優先度（1-4）
      • due_date (number, optional)：ミリ秒単位のタスクの期限
      • tags (string[], optional)：タスクに追加するタグ名の一覧
    • 戻り値：作成したタスクの詳細

16. get_task

    • 特定のタスクの詳細を取得します
    • 入力：
      • task_id (string)：タスクの ID
    • 戻り値：説明やステータスなどを含むタスクのすべての詳細

17. update_task

    • タスクのプロパティを更新します
    • 入力：
      • task_id (string)：タスクの ID
      • name (string, optional)：新しいタスク名
      • description (string, optional)：新しいタスクの説明
      • priority (number, optional)：新しいタスクの優先度（1-4）
      • due_date (number, optional)：ミリ秒単位の新しい期限
      • tags (string[], optional)：新しいタグ名の一覧
    • 戻り値：更新されたタスクの詳細

18. update_task_status

    • タスクのステータスを更新します
    • 入力：
      • task_id (string)：タスクの ID
      • status (string)：タスクの新しいステータス
    • 戻り値：更新されたタスクの詳細

19. assign_task

    • タスクにユーザーを割り当てます
    • 入力：
      • task_id (string)：タスクの ID
      • assignee_ids (string[])：タスクに割り当てるユーザー ID の一覧
    • 戻り値：割り当ての確認

20. get_task_subtasks

    • タスクのサブタスクを取得します
    • 入力：
      • task_id (string)：タスクの ID
    • 戻り値：詳細を含むサブタスクの一覧

21. delete_task

    • タスクを削除します
    • 入力：
      • task_id (string)：削除するタスクの ID
    • 戻り値：削除の確認

22. move_task

    • タスクを別のリスト／ボードに移動します
    • 入力：
      • task_id (string)：移動するタスクの ID
      • list_id (string)：移動先のリスト／ボードの ID
    • 戻り値：更新されたタスクの詳細

23. duplicate_task

    • タスクを複製します。別のリスト／ボードへの複製も指定できます
    • 入力：
      • task_id (string)：複製するタスクの ID
      • list_id (string, optional)：移動先のリスト／ボードの ID
    • 戻り値：複製したタスクの詳細

24. create_subtask

    • 親タスクのサブタスクを作成します
    • 入力：
      • parent_task_id（string）：親タスクの ID
      • name（string）：サブタスクの名前
      • description（string、任意）：サブタスクの説明
      • priority（number、任意）：サブタスクの優先度（1～4）
      • due_date（number、任意）：サブタスクの期限（ミリ秒）
      • tags（string[]、任意）：サブタスクのタグ名の一覧
    • 戻り値：作成したサブタスクの詳細

25. add_comment

    • タスクにコメントを追加します
    • 入力：
      • task_id（string）：タスクの ID
      • comment_text（string）：コメントのテキスト内容
    • 戻り値：追加したコメントの詳細

26. add_attachment

    • URL を指定してタスクに添付ファイルを追加します
    • 入力：
      • task_id（string）：タスクの ID
      • attachment_url（string）：追加する添付ファイルの URL
    • 戻り値：追加した添付ファイルの詳細

27. bulk_update_tasks

    • リスト内の複数のタスクを一括で更新します
    • 入力：
      • list_id（string）：タスクを含むリスト／ボードの ID
      • task_ids（string[]）：更新するタスク ID の一覧
      • name（string、任意）：すべてのタスクに設定する新しい名前
      • description（string、任意）：すべてのタスクに設定する新しい説明
      • status（string、任意）：すべてのタスクに設定する新しいステータス
      • priority（number、任意）：すべてのタスクに設定する新しい優先度（1～4）
      • due_date（number、任意）：すべてのタスクに設定する新しい期限（ミリ秒）
      • tags（string[]、任意）：すべてのタスクに設定する新しいタグ名の一覧
    • 戻り値：一括更新の確認

28. bulk_delete_tasks

    • 複数のタスクを一括で削除します
    • 入力：
      • task_ids（string[]）：削除するタスク ID の一覧
    • 戻り値：一括削除の確認

カスタムフィールドツール

29. get_custom_fields

    • リスト／ボードのすべてのカスタムフィールドを取得します
    • 入力：
      • list_id（string）：リスト／ボードの ID
    • 戻り値：ID、名前、種類、設定を含むカスタムフィールドの一覧

30. set_custom_field_value

    • フィールド ID を使用して、タスクのカスタムフィールド値を設定します
    • 入力：
      • task_id（string）：タスクの ID
      • field_id（string）：カスタムフィールドの ID
      • value（any）：カスタムフィールドに設定する値
    • 戻り値：カスタムフィールドの更新確認

31. set_custom_field_value_by_name

    • フィールド名を使用して、タスクのカスタムフィールド値を設定します
    • 入力：
      • task_id（string）：タスクの ID
      • list_id（string）：リストの ID（名前でカスタムフィールドを検索するために必要）
      • field_name（string）：カスタムフィールドの名前
      • value（any）：カスタムフィールドに設定する値
    • 戻り値：カスタムフィールドの更新確認

32. remove_custom_field_value

    • タスクからカスタムフィールド値を削除します
    • 入力：
      • task_id（string）：タスクの ID
      • field_id（string）：カスタムフィールドの ID
    • 戻り値：カスタムフィールドの削除確認

インストール

前提条件

• Python 3.10 以降
• API キーを持つ ClickUp アカウント

uv を使用する（推奨）

uv を使用する場合、特別なインストールは必要ありません。uvx を使用して、clickup-mcp-server を直接実行します。

uv --directory "/path/to/clickup-mcp-server" run clickup-mcp-server --api-key YOUR_API_KEY

または、.env ファイルを使用してください（「設定」セクションを参照）。

PIP を使用する

別の方法として、pip 経由で clickup-mcp-server をインストールできます。

pip install clickup-mcp-server

インストール後、次のようにスクリプトとして実行できます。

python -m clickup_mcp_server --api-key YOUR_API_KEY

設定

API キー

このサーバーを使用するには ClickUp API キーが必要です。ClickUp API Settings から取得できます。

API キーは次の 2 つの方法で指定できます。

1. コマンドライン引数：--api-key YOUR_API_KEY
2. .env ファイル内の環境変数：

   CLICKUP_API_KEY=your_api_key_here
   

Claude Desktop での使用方法

以下を claude_desktop_config.json に追加します。

"mcpServers": {
  "clickup": {
    "command": "uvx",
    "args": ["clickup-mcp-server", "--api-key", "YOUR_API_KEY"]
  }
}

"mcpServers": {
  "clickup": {
    "command": "docker",
    "args": ["run", "--rm", "-i", "-e", "CLICKUP_API_KEY=YOUR_API_KEY", "mcp/clickup"]
  }
}

"mcpServers": {
  "clickup": {
    "command": "python",
    "args": ["-m", "clickup_mcp_server", "--api-key", "YOUR_API_KEY"]
  }
}

VS Code での使用方法

手動でインストールする場合は、以下の JSON ブロックを VS Code のユーザー設定（JSON）ファイルに追加します。Ctrl + Shift + P を押して Preferences: Open Settings (JSON) と入力すると設定できます。

必要に応じて、ワークスペース内の .vscode/mcp.json というファイルに追加することもできます。これにより、設定を他のユーザーと共有できます。

.vscode/mcp.json ファイルでは mcp キーは不要です。

{
  "mcp": {
    "servers": {
      "clickup": {
        "command": "uvx",
        "args": ["clickup-mcp-server"],
        "env": {
          "CLICKUP_API_KEY": "YOUR_API_KEY"
        }
      }
    }
  }
}

Docker でインストールする場合：

{
  "mcp": {
    "servers": {
      "clickup": {
        "command": "docker",
        "args": [
          "run",
          "--rm",
          "-i",
          "-e", "CLICKUP_API_KEY=YOUR_API_KEY",
          "mcp/clickup"
        ]
      }
    }
  }
}

Zed での使用方法

Zed の settings.json に追加します。

"context_servers": [
  "mcp-server-clickup": {
    "command": {
      "path": "uvx",
      "args": ["clickup-mcp-server"]
    },
    "env": {
      "CLICKUP_API_KEY": "YOUR_API_KEY"
    }
  }
],

"context_servers": {
  "mcp-server-clickup": {
    "command": {
      "path": "python",
      "args": ["-m", "clickup_mcp_server"]
    },
    "env": {
      "CLICKUP_API_KEY": "YOUR_API_KEY"
    }
  }
},

使用例

Claude によるタスク管理

Claude は ClickUp のタスク管理を支援できます。

1. タスク計画の作成： ClickUp の特定のタスクに基づいて計画を作成するよう Claude に依頼します。Claude は以下を行います。

   • 名前または ID でタスクを検索する
   • 説明とサブタスクを分析する
   • タスクを完了するための構造化された計画を作成する

2. タスクの自動化： コード関連の指示が含まれるタスクの場合、Claude は以下を行えます。

   • ClickUp からタスクの詳細を取得する
   • タスクのステータスを「In Progress」に更新する
   • タスクの要件に従ってコードを実装する
   • 完了したサブタスクにチェックを付ける
   • 完了時にステータスを「Ready for Review」に更新する

3. タスクのレポート作成： 特定のステータスのタスクの要約を作成するよう Claude に依頼します。

   • 「In Progress」とマークされたすべてのタスクを取得する
   • 完了見込みを含むステータスレポートを作成する
   • ブロッカーや依存関係に関する新しいタスクを作成する

4. カスタムフィールドの管理： Claude はカスタムフィールドを活用して、ワークフローを改善できます。

   • プロジェクト内のすべてのカスタムフィールドを一覧表示し、利用可能なメタデータを確認する
   • PR の作成時に「GitHub Pull Request URL」などのカスタムフィールドの値を設定する
   • 「Sprint」、「Story Points」、「Priority」などのプロジェクト追跡フィールドを更新する
   • 例：「このブランチの PR を作成し、関連する ClickUp タスクの『GitHub Pull Request URL』カスタムフィールドに GitHub URL を追加する」

デバッグ

詳細なログを出力するには、-v または -vv フラグを指定してサーバーを実行します。

uvx clickup-mcp-server -vv

MCP インスペクターを使用してサーバーをデバッグできます。

npx @modelcontextprotocol/inspector uvx clickup-mcp-server

開発

開発環境のセットアップ

1. リポジトリをクローンします。

   git clone https://github.com/yourusername/clickup-mcp-server.git
   cd clickup-mcp-server
   

2. 開発用の依存関係をインストールします。

   uv pip install -e ".[dev]"
   

3. テストを実行します。

   pytest
   

Docker ビルド

Docker イメージをビルドします。

docker build -t mcp/clickup .

実装状況

この MCP サーバーでは、ClickUp の主要な機能の大部分を実装しています。以下に、実装済みの機能と今後実装予定の機能を詳しく示します。

タスク管理 ✅

主要なタスク管理機能はすべて実装済みです。

ワークスペースの整理 ✅

ワークスペースの整理に関するすべての機能が実装されています。

その他の機能 🔧

一部の高度な機能は実装済みで、その他の機能は今後のリリースでの提供を予定しています。

凡例：

• ✅ 実装済み
• 🔄 予定または進行中

ライセンス

この MCP サーバーは MIT License の下でライセンスされています。つまり、MIT License の利用規約に従う限り、ソフトウェアを自由に使用、変更、配布できます。詳しくは、プロジェクトリポジトリ内の LICENSE ファイルをご覧ください。