clickup-mcp-full

ネストされたサブタスクツリー全体を1回の呼び出しで読み取れる ClickUp MCP サーバーです。

@twofeetup/clickup-mcp をフォークせずにラップしているため、上流の修正は依存関係の更新だけで取り込めます。このサーバーはその上に get_task_tree を追加し、小さなモデルを確実に誤った方向へ導くツール説明を1つ書き換え、妥当なデフォルトのツールセットを固定しています。

なぜ

上流でサブタスクを取得する唯一の経路は、include_subtasks を指定した search_tasks です。これは GET /task/{id}?subtasks=true を呼び出し、直接の子だけの完全なタスクオブジェクトを返します。サブタスクが複数階層にわたって数多く存在するタスクでは、これは不完全であるばかりか、エージェントのコンテキストウィンドウにとっても壊滅的です。ノードごとに1リクエストする代替手段は、さらに悪い結果になります。

get_task_tree はその代わりに、そのタスクを含むリストを一度だけ走査します。ClickUp の GET /list/{id}/task?subtasks=true は、リスト内のすべてのタスクを parent ポインタと一緒に返すため、ツリーはローカルで再構築されます。深さや幅に関係なく、リクエストは合計2回だけで済み、出力はタスクごとにコンパクトな1行になります。

Task tree for 86capt3b: 23 task(s) including the root.
Statuses: in progress: 3, open: 14, complete: 6
List: Q3 Delivery

86capt3b  [in progress]  Migrate billing service  <ivan>
  86captk1  [complete]  Audit current schema  <olena>
  86captk2  [in progress]  Write migration scripts  <ivan>
    86captm7  [open]  Handle partial refunds
    86captm8  [open]  Backfill historical rows
  86captk3  [open]  Cutover plan

Related MCP server: ClickUp MCP

インストール

クローンやビルドは不要です。エージェントにパッケージを指定すると、初回起動時にフェッチされます。

Claude Code

claude mcp add clickup_full_local \
  --env CLICKUP_API_KEY=pk_your_token \
  --env CLICKUP_TEAM_ID=9012345678 \
  -- npx -y github:breckenreed/clickup-mcp-full

Claude Desktop、Cursor、Windsurf、または mcpServers JSON を使うクライアント

{
  "mcpServers": {
    "clickup_full_local": {
      "command": "npx",
      "args": ["-y", "github:breckenreed/clickup-mcp-full"],
      "env": {
        "CLICKUP_API_KEY": "pk_your_token",
        "CLICKUP_TEAM_ID": "9012345678"
      }
    }
  }
}

Hermes（~/.hermes/config.yaml）

mcp_servers:
  clickup_full_local:
    command: npx
    args: ["-y", "github:breckenreed/clickup-mcp-full"]
    env:
      CLICKUP_API_KEY: "${CLICKUP_API_KEY}"
      CLICKUP_TEAM_ID: "${CLICKUP_TEAM_ID}"
    connect_timeout: 60
    keepalive_interval: 60
    idle_timeout_seconds: 1800

グローバルインストール（起動のたびに GitHub から解決したくない場合）:

npm install -g github:breckenreed/clickup-mcp-full

その後は、引数なしで clickup-mcp-full をコマンドとして使います。

認証情報

ClickUp の個人用トークンは、それ自体には一切スコープを持ちません。トークンは作成したユーザーとして動作し、そのユーザーの権限を継承します。書き込みできないエージェントを作りたい場合は、ツール選択に頼るのではなく、読み取り専用の ClickUp アカウントでトークンを作成してください。

ツール

上流にはローカルファイルを ClickUp にアップロードする attach_file_to_task も同梱されていますが、こちらはデフォルトでオフです。操作ごとの確認なしで動くエージェントでは、エージェントが読み取ったプロンプトインジェクションを、そのまま漏洩経路=データ送信経路に変えてしまうためです。必要なら意図的に有効にしてください:

ENABLED_TOOLS=get_workspace_hierarchy,search_tasks,manage_task,task_comments,get_container,manage_container,find_members,operate_tags,task_time_tracking,attach_file_to_task

オプション

共有ワークスペースでは REQUEST_SPACING を上げてください。 デフォルトでは毎秒およそ10リクエストが許容されますが、ClickUp のトークン単位の制限は、ほとんどのプランでだいたい毎分100リクエストです。制限はツール単位ではなくトークン単位で数えられるため、エージェントがそれを尽くすと、同じトークンで動いている他の連携もすべて止まります。700 にすれば、毎分100回の上限を下回ります。

挙動の注意点

別のリストにあるサブタスク。 ツリーは、ルートタスクが含まれるリストを走査して構築されます。ワークスペースでサブタスクを親とは別のリストに置いている場合、それらは現れません。その場合サーバーは、タスクエンドポイントが報告する直接子にフォールバックします。このケースに当てはまり、対処が必要なら issue を開いてください。

search_tasks の説明文。 上流の説明文（"Works 3 ways"）があるために、小さなモデルは 86cap3b のような素のID を customTaskId に入れてしまいます。customTaskId が受け付けるのは DEV-123 のような接頭辞付き ID だけです。そうした呼び出しはワークスペース検索の方へフォールし、At least one filter parameter is required という、実際とは別の問題を指すエラーで失敗します。その結果、モデルはフィールドを修正するかわりにフィルタを付け加えようとします。このサーバーは、その説明文をモデルが実際に必要とするただひとつのルールに置き換えます。

bind mount されたホームディレクトリで Docker 実行する場合。 エージェントが HOME をバインドマウントの場所に向けて MCP サーバーを起動している場合、npx は接続のたびにパッケージキャッシュをそのマウント越しに再構築し、数分かかってタイムアウトすることがあります。代わりにイメージ内にグローバルインストールし、command: をバイナリに指定してください。

トラブルシューティング

サーバーが起動してツールを一覧表示できることを確認してください:

CLICKUP_API_KEY=pk_... CLICKUP_TEAM_ID=... npx -y github:breckenreed/clickup-mcp-full --help

Missing required environment は環境変数がプロセスに届いていないことを意味します。多くのクライアントでは、シェルではなくサーバー自身の env ブロックに変数を設定する必要があります。

どのツールでも 401 が返る場合は、トークンが誤っているか失効しています。429 はレートリミットに達したことを示すので、REQUEST_SPACING を上げてください。

ライセンス

MIT です。ラップしている上流のサーバーと同じです。@twofeetup/clickup-mcp は、@taazkareem/clickup-mcp-server の先行有料ツリーから続く、MIT ライセンスのコミュニティ継続版です。