clickup-mcp

ClickUp MCPサーバー（Claude用） — ClickUpのタスク、スペース、フォルダ、リスト、コメントをMCPツールとして公開します。

技術スタック: Python 3.12 + uv + FastMCP (Starlette/FastAPI)

クイックスタート

# Install dependencies
cd D:\leo\mcp-server\clickup-mcp
uv sync

# Run in stdio mode (for Claude Desktop)
$env:CLICKUP_API_TOKEN="pk_xxxxx"
uv run clickup-mcp

Related MCP server: Clickup Universal MCP Server

設定

.env.example を .env にコピーし、値を入力してください：

APIトークンを取得するには：ClickUp → 設定 → アプリ → APIトークン

Claude Desktopのセットアップ

claude_desktop_config.json に追加：

{
  "mcpServers": {
    "clickup": {
      "command": "uv",
      "args": ["run", "--directory", "D:/leo/mcp-server/clickup-mcp", "clickup-mcp"],
      "env": {
        "CLICKUP_API_TOKEN": "pk_xxxxx"
      }
    }
  }
}

トランスポートモード

stdio (Claude Desktop / CLI)

$env:CLICKUP_API_TOKEN="pk_xxxxx"
uv run clickup-mcp

HTTP — シングルテナント

$env:CLICKUP_API_TOKEN="pk_xxxxx"
$env:MCP_TRANSPORT="http"
$env:MCP_HTTP_PORT="8080"
uv run clickup-mcp

HTTP — ゲートウェイ / マルチテナント

$env:MCP_TRANSPORT="http"
$env:AUTH_MODE="gateway"
uv run clickup-mcp
# Each request must include: X-Clickup-Token: pk_xxxxx

利用可能なツール (28)

個人のClickUpユーザーIDを見つける

clickup_list_members を使用します。ClickUpのネイティブ GET /team レスポンスはチームごとに完全なメンバーリストを埋め込みますが (teams[].members[].user.{id,username,email})、clickup_get_workspaces はレスポンスを小さく保つためにそれを取り除くため、人物を検索する場所としては適していません。clickup_list_members は同じ基盤エンドポイントを読み取り、メンバーリストをフラットで目的に特化した形状 (id/username/email/team_id/role) に投影するため、呼び出し元が完全なワークスペース/チームオブジェクトから自分で掘り出す必要はありません。clickup_list_tasks_for_person は内部的に同じルックアップを使用して email を user_id に解決します。

既知のギャップ：ClickUpのチームメンバーオブジェクトには、信頼できる「このメンバーは無効化されているか」フィールドがありません — clickup_list_members は active フィールドを返しません。なぜなら、それを裏付ける実際のデータが存在しないからです（生のオブジェクトに存在する唯一の status フィールドである invited_by.status は、招待者を説明するものであり、メンバーを説明するものではありません）。

clickup_search_tasks はすでに status.type を返します

ここにある他のすべての読み取りツールと同様に、clickup_search_tasks と clickup_get_task はClickUpの生のタスクオブジェクトを変更せずにそのまま通過させます — これには status オブジェクトの type フィールド (open / custom / closed / done) も含まれます。これは、カスタム名のステータスが完了とみなされるかどうかを判断する唯一の信頼できる方法です。このためのコード変更は必要ありませんでした。すでに存在していました。clickup_list_tasks_for_person は、利便性のために返される各タスクに status_type として明示的に表示します。

EOS RocksがこのClickUpワークスペースでどのように表現されるか

実際のロックタスクのフィールドを直接検査して確認済み（2026-08-18、推測ではありません）：Rocksは、文字通り「Rocks」という名前のリストに存在する通常のClickUpタスクです（スペース「Company」> フォルダ「EOS Traction」の下にあります）。それぞれに専用のカスタムフィールドがあります：Quarter（ドロップダウン、"Q1 2024".."Q4 2026"）、Rocks Status（On Hold / Off Track / On Track / Completed / Blocked / At Risk）、Rock Type（Company / Individual / Departmental / Team Rock）、Department、および Progress（手動）または Progress %（自動、チェックリストロールアップ）のいずれかによる進捗状況。これはClickUp Goals APIでも、メタデータのない単純なタスクリストでもありません — タスクとカスタムフィールドの組み合わせです。

clickup_list_rocks_for_org は、トークンから見えるすべてのワークスペースにわたって「Rocks」という名前のすべてのリストを（ハードコードされたIDではなく名前で、スペース/フォルダが再編成される場合に備えて）検出し、これらのフィールドを読み取り、正規化します：

• quarter：ClickUpの「Q3 2026」ラベルは 2026-Q3 に変換されます（およびその逆も、quarter 入力フィルター用）。

• status：ClickUpの6つの生のオプションは、5つの値の契約 (on_track/off_track/done/missed/open) にマッピングされます — 正確なマッピングと、missed が決して出力されない理由については、rocks.py の _STATUS_MAP コメントを参照してください（ClickUpのデータで「時間切れ」と一般的な「軌道から外れている」を区別するものは何もなく、期限切れの due_date からそれを導出することは未確認のビジネスロジックの仮定となるため、ここでは行われていません）。

• measurable：このリストには専用のフィールドは存在しません。タスクの説明にフォールバックします。それも空の場合は null（決して作り出されません）。

• weekly_status：構造化されたソースはどこにも見つかりませんでした（カスタムフィールドでも、コメントから派生したものでもありません） — 常に [] として返されます。組織がこれをClickUpで他の方法で追跡し始めた場合は、再検討してください。

添付ファイルと画像

ClickUpのREST APIには、ファイルをコメントに直接添付する方法はありません — タスクにのみ添付できます（POST /task/{task_id}/attachment、clickup_attach_task_file がラップするもの）。また、添付ファイルを削除/更新するエンドポイントもありません。再アップロードすると古い添付ファイルを置き換えるのではなく新しい添付ファイルが追加され、削除するにはClickUpのWeb/デスクトップアプリが必要です。ClickUp自身の公式MCPサーバーのツール説明を確認しても確認済みです — 同じ分割です（添付ファイルをサポートしない Create Task Comment ツールと、別の Attach File to Task ツール）。

コメント内に画像をインラインで表示させるには、基本的なトリックは次のとおりです：まずファイルをタスクにアップロードし、次にファイルのレスポンスから返されたURLをコメントテキスト内のMarkdown画像構文で参照します — ClickUpのコメントレンダラーはそれを単なるリンクではなく実際の画像としてインライン表示します。clickup_create_comment_with_image は両方のステップを1回の呼び出しで実行します：

clickup_create_comment_with_image(task_id, file_content_base64, filename)
# internally:
#   1. POST /task/{task_id}/attachment  -> {"url": "...", ...}
#   2. POST /task/{task_id}/comment     comment_text = "![filename](url)"

代わりに手動で行う場合（例：画像の周りに他のテキストを追加するため）、2つのツールを自分で呼び出します：

1. result = clickup_attach_task_file(task_id, file_content_base64, filename)
   -> result["url"] is the uploaded file's URL

2. clickup_create_task_comment(
     task_id,
     comment_text=f"![{filename}]({result['url']})"
   )

APIリファレンス

• ClickUp API v2 ドキュメント

• タスク添付ファイルの作成