Clickup Mcp

AI アシスタント向け ClickUp MCP

AI アシスタントが ClickUp ワークスペースを操作できるようにする Model Context Protocol（MCP）サーバーです。コメントや画像を含む完全なタスクコンテキストを取得したり、プロジェクト全体を検索したり、タスクを作成・更新したり、コメントで共同作業したり、時間を記録したりできます。これらすべてを自然言語で行えます。

この MCP と ClickUp 公式 MCP の比較

こちらもご覧ください：ClickUp 公式 MCP ドキュメント

機能	この MCP	ClickUp 公式 MCP
セットアップ	ローカルで npm/npx をインストール	リモート MCP（インストール不要）
認証	API キーのみ	OAuth のみ
タスクコンテキスト	コメント、ステータス履歴、インライン画像を含む完全な情報	完全なコンテキストの取得には複数のツール呼び出しが必要
画像サポート	読み取りと書き込みに対応：サイズを賢く調整したインライン画像、および  による自動アップロード	別のツール呼び出しでアップロード。base64 は約200KBまで
検索	最近のタスクのあいまい検索（対象範囲に制限あり）	ClickUp データベース全体を検索
ドキュメント	CRUD 操作	CRUD とドキュメント検索
時間の追跡	エントリーの表示と作成	タイマーとエントリー
チャット連携	非対応	対応
接続済みアプリ	非対応	Connected Search
最適な用途	コーディングツール、自動化、コンテキスト収集	チャットアプリ、タスク管理
サポート	コミュニティ（オープンソース）	ClickUp 公式

この MCP を選ぶ場合：

• AI コーディングツール向けに、インライン画像を含む豊富なタスクコンテキストが必要な場合
• ローカルファイルパスを指定してスクリーンショットをチケットに書き込みたい場合（ローカルで実行すると、base64 を使わずに MCP がファイルを直接読み込みます）
• 自動化または CI/CD パイプラインで API キー認証が必要な場合
• 開発ワークフローに最適化された read-minimal モードを使いたい場合

ClickUp 公式 MCP を選ぶ場合：

• エンタープライズのセキュリティコンプライアンスのために OAuth 認証が必要な場合
• チャット連携または Connected Search 機能が必要な場合
• 公式サポートを受けたい、またはローカルへのインストールを避けたい場合

できること

自然言語で、ClickUp の強力なアクションを実行できます。

エージェント型のコーディングと開発：

• 「CU-abc123を確認して、関連するコードを見つけてください」
• 「https://app.clickup.com/t/12a23b45c に記載されているとおりにダッシュボードを構築してください」
• 「タスク CU-xyz789 を確認して、コメントに記載されているバグを修正してください」
• 「インテグレーションタスクに記載されている API エンドポイントを実装してください」

時間追跡と生産性：

• 「XYZ プロジェクトのクライアントとの打ち合わせを2時間記録してください」
• 「今週、開発タスクにどのくらい時間を使いましたか？」
• 「認証機能のコードレビューを30分記録してください」

スマート検索と情報探索：

• 「CSV インポートについて言及したタスクはどれですか？」
• 「ペイメントゲートウェイのインテグレーションに関連するタスクをすべて見つけてください」
• 「ユーザーからログインの問題が報告されているタスクを表示してください」

日々のワークフロー管理：

• 「今日は何をする必要がありますか？」
• 「フロントエンドのリストに、ダッシュボードのバグ修正タスクを作成してください」
• 「API ドキュメントのタスクを「レビュー中」ステータスに更新してください」
• 「モバイルアプリのリリースを妨げているタスクは何ですか？」

豊富なコンテキストとコラボレーション：

• 「ユーザー認証タスクのコメントをすべて表示してください」
• 「データベース移行に関する最新の更新は何ですか？」
• 「新しいワイヤーフレームについて、デザインタスクにコメントを追加してください」

ドキュメント管理：

• 「hauptsache.net スペースで求人に関するドキュメントを見つけてください」
• 「すべてのスペースから API ドキュメントを検索してください」
• 「開発スペースの API ドキュメントを読んでください」
• 「モバイルアプリプロジェクトの新しい要件ドキュメントを作成してください」
• 「今日決定した内容で議事録を更新してください」
• 「プロダクト戦略スペースにはどのようなドキュメントがありますか？」

主な機能

🔍 インテリジェント検索

• タスク名、説明、コメントを対象としたあいまい検索
• 国際的なチーム向けの多言語検索に対応
• 担当者、プロジェクト、ステータス、メタデータで絞り込み

💬 完全なコンテキスト

• コメント履歴とチームのディスカッション（トップレベルのコメントを最大250件）、スレッド形式の返信を含む
• 画像を埋め込んだタスクの説明
• リストの説明とプロジェクトのガイドライン
• ページ移動に対応したドキュメントの内容
• タスクの履歴と決定事項をすべて参照可能

⏱️ 時間追跡

• 説明を付けて時間エントリーを記録
• 過去の時間ログとエントリーを表示
• タスクまたは期間を指定して時間エントリーを検索

📋 タスクとドキュメントの管理

• Markdown 形式の説明を付けてタスクを作成、更新
• ドキュメントやページを作成、閲覧、更新
• コメントを追加してチームメンバーとコラボレーション
• 優先度、期限、担当者、タグを管理
• 時間の見積もりとカスタムフィールドの値を管理

🔒 安全機能

• 説明は追記のみ：説明フィールドが上書きされることはありません。新しい内容はタイムスタンプ付きで安全に追記されます
• 通常のフィールド更新：ステータス、優先度、担当者、タグ、日付は通常どおり更新できます（ClickUp の履歴から簡単に元に戻せます）

インストール

前提条件

すべてのインストール方法で、次の情報が必要です。

• CLICKUP_API_KEY（プロフィールアイコン > Settings > Apps > API Token。通常は pk_ で始まります）
• CLICKUP_TEAM_ID（設定画面を開いているときの URL に含まれる7～10桁の数字）

オプション 1：MCPB バンドル（Claude Desktop 推奨）

ビルド済みバンドルをリリースページからダウンロードしてください。この方法では Node.js のインストールは不要です。

API キーとチーム ID の入力を求める設定画面が表示されます。

オプション 2：NPX によるインストール

この方法では最新バージョンに自動的に更新されるため、最新機能を使いたいユーザーにおすすめです。

Claude Desktop、Windsurf、Cursor などの場合：

以下を MCP 設定ファイルに追加します。

{
  "mcpServers": {
    "clickup": {
      "command": "npx",
      "args": [
        "@hauptsache.net/clickup-mcp@latest"
      ],
      "env": {
        "CLICKUP_API_KEY": "your_api_key",
        "CLICKUP_TEAM_ID": "your_team_id"
      }
    }
  }
}

your_api_key と your_team_id を実際の ClickUp 認証情報に置き換えてください。

この設定の追加先：

• Claude Desktop：設定 > 開発者 > 設定を編集
• Windsurf：MCP 設定ファイルに追加
• Cursor：MCP 設定パネルから設定

オプション 3：コーディングツールとの統合

Claude Code（CLI）：

claude mcp add --scope user clickup \
  --env CLICKUP_API_KEY=YOUR_KEY \
  --env CLICKUP_TEAM_ID=YOUR_ID \
  --env CLICKUP_MCP_MODE=read-minimal \
  --env MAX_IMAGES=16 \
  --env MAX_RESPONSE_SIZE_MB=4 \
  -- npx -y @hauptsache.net/clickup-mcp

Claude Code は多くの画像を扱えるため、上限を増やすことをおすすめします。

CLICKUP_MCP_MODE=read-minimal に注意してください。これは私のおすすめの使用方法ですが、ほかのモードを使ってもかまいません。

OpenAI Codex： ~/.codex/config.toml ファイルに以下の行を追加します。

[mcp_servers.clickup]
command = "npx"
args = ["-y", "@hauptsache.net/clickup-mcp@latest"]
env = { "CLICKUP_API_KEY" = "YOUR_KEY", "CLICKUP_TEAM_ID" = "YOUR_ID", "CLICKUP_MCP_MODE" = "read-minimal" }

Codex は MCP の画像を扱えないようです。詳しくはこの issueをご覧ください。

CLICKUP_MCP_MODE=read-minimal に注意してください。これは私のおすすめの使用方法ですが、ほかのモードを使ってもかまいません。

MCP のモードと利用可能なツール

ClickUp MCP では、機能、セキュリティ、パフォーマンスのバランスを取るために、3 つの動作モードをサポートしています。

• 🚀 read-minimal：AI コーディングアシスタントやコンテキストの収集に最適です
• 📖 read：プロジェクトの調査やワークフローの把握に役立つ、完全な読み取り専用アクセスです
• ✏️ write（デフォルト）：タスク管理や生産性向上のワークフローに必要なすべての機能を利用できます

ツール	read-minimal	read	write	説明
getTaskById	✅	✅	✅	コメント（スレッド形式の返信を含む）、画像、メタデータを含むタスクの詳細をすべて取得します
addComment	❌	❌	✅	タスクにコメントを追加するか、parent_comment_id を指定してコメントスレッド内に返信します
editComment	❌	❌	✅	追加のコメントを投稿する代わりに、24 時間以内であれば自分のコメントを修正します
updateTask	❌	❌	✅	タスク（ステータス、優先度、担当者など）を更新します。説明は追記することも、完全に置き換えることもできます
createTask	❌	❌	✅	Markdown を全面的にサポートした新しいタスクを作成します
searchTasks	✅	✅	✅	内容、キーワード、担当者、プロジェクトのコンテキストでタスクを検索します
searchSpaces	❌	✅	✅	ワークスペースの構造、プロジェクトの編成、ドキュメントを閲覧します
getListInfo	❌	✅	✅	タスク作成に利用できるリストの詳細とステータスを取得します
updateListInfo	❌	❌	✅	リストの説明を安全に追記のみで更新します（既存の内容は保持されます）
getTimeEntries	❌	✅	✅	時間記録を表示し、プロジェクト全体で費やした時間を分析します
createTimeEntry	❌	❌	✅	タスク追跡用の時間記録を追加します
readDocument	❌	✅	✅	ドキュメントの詳細、ページ構成、ナビゲーション付きのコンテンツを取得します
searchDocuments	❌	✅	✅	あいまい検索とスペースによる絞り込みで、名前やスペースからドキュメントを検索します
updateDocumentPage	❌	❌	✅	置き換えモードまたは追記モードで、既存ページの内容や名前を更新します
createDocumentOrPage	❌	❌	✅	最初のページを含む新しいドキュメントを作成するか、既存のドキュメントにページやサブページを追加します

モードの設定

MCP の設定にモードを追加します：

{
  "mcpServers": {
    "clickup": {
      "command": "npx",
      "args": ["-y", "@hauptsache.net/clickup-mcp@latest"],
      "env": {
        "CLICKUP_API_KEY": "your_api_key",
        "CLICKUP_TEAM_ID": "your_team_id",
        "CLICKUP_MCP_MODE": "read"
      }
    }
  }
}

設定

この MCP サーバーは、環境変数を使用して設定できます。デスクトップ拡張機能（.mcpb）のインストーラーでは、API キー、チーム ID、主要言語、アップロードサイズの上限、コメントの編集可能時間をフォームから設定できます。残りの変数は、サーバー環境で直接設定する必要があります。

• CLICKUP_API_KEY：（必須）ClickUp API キーです。
• CLICKUP_TEAM_ID：（必須）ClickUp のチーム ID（以前のワークスペース ID）です。
• CLICKUP_MCP_MODE：（任意）利用可能なツールを制御します。選択肢：read-minimal、read、write（デフォルト）。
• MAX_IMAGES：（任意）getTaskById でタスクごとに返す画像の最大数です。デフォルトは 4 です。
• MAX_RESPONSE_SIZE_MB：（任意）getTaskById の最大レスポンスサイズ（メガバイト単位）です。重要度の高い画像が上限内に収まるよう、インテリジェントなサイズ予算管理を使用します。デフォルトは 1 です。
• MAX_UPLOAD_SIZE_MB：（任意）コメントまたは説明の書き込み時にアップロードする単一画像の最大サイズです。デフォルトは 10 です。
• CLICKUP_COMMENT_EDIT_WINDOW_HOURS：（任意）作成後、editComment でコメントを書き換えられる時間です。デフォルトは 24 です。コメントの編集を完全に無効にするには、0 を設定します。
• CLICKUP_PRIMARY_LANGUAGE：（任意）ClickUp のタスクで使われる主要言語のヒントです（例：ドイツ語の場合は "de"、英語の場合は "en"）。これにより、searchTask ツールは多言語検索向けに、説明でより適切なガイダンスを提供できます。
• LANG：（任意）CLICKUP_PRIMARY_LANGUAGE が設定されていない場合、MCP はこの標準環境変数（例："en_US.UTF-8"、"de_DE"）を代替として確認し、主要言語を推測します。

言語を考慮した検索ガイダンス

searchTask ツールの説明は、検出された主要言語に応じて動的に調整されます。

• CLICKUP_PRIMARY_LANGUAGE または LANG から既知の主要言語（例：ドイツ語）が推測される場合、最適な検索結果を得るため、英語と検出された言語（例：ドイツ語）の両方で検索語を入力するよう、ツールの説明で具体的に推奨します。
• 主要言語が検出されない場合は、多言語ワークスペース向けのより一般的な推奨事項が提示されます。

この機能は、MCP 自体に翻訳を行わせることなく、ユーザーのクエリ（多くの場合は英語）の言語と ClickUp のタスクの言語が異なる場合に、検索の有効性を高めることを目的としています。引き続き、MCP を呼び出すエージェントが二言語の検索語を提供する責任を負いますが、MCP は言語のヒントがある場合、より具体的なアドバイスを提示します。

Markdown 形式のサポート

タスクの説明とリストのドキュメントでは、Markdown の書式を全面的にサポートしています。

例

Markdown を使ったタスクの作成：

Create a task called "API Integration" with description:
# API Integration Requirements

## Authentication
- Implement OAuth 2.0 flow
- Add JWT token validation
- **Priority**: High security standards

## Endpoints
1. `/api/users` - User management
2. `/api/data` - Data retrieval
3. `/api/webhook` - Event notifications

## Testing
- [ ] Unit tests for auth flow
- [ ] Integration tests
- [ ] Load testing with 1000+ concurrent users

> **Note**: This replaces the legacy REST implementation

See related task: https://app.clickup.com/t/abc123

追記のみの更新（安全）： タスクの説明を更新すると、内容は安全に追記されます。

[Existing task description content]

---
**Edit (2024-01-15):** Added new acceptance criteria based on client feedback:
- Must support mobile responsive design
- Performance requirement: < 2s load time

これにより、明確な監査証跡を維持しながら、既存の内容が失われることはありません。

チケットへの画像の書き込み

addComment、editComment、createTask、updateTask は、通常の Markdown として画像を受け付けます。このサーバーはローカルで実行されるため、ファイルを自ら読み取ります。そのため、ローカルパスだけで十分です。

Ist umgesetzt. So sieht es aus:

**1. Login öffnen** – der Kunde gibt nur seine E-Mail-Adresse ein.

![Die Login-Maske fragt nur nach der E-Mail](/Users/me/shots/login.png)

受け付けるソース：ローカルファイルパス、data: URI、http(s) URL（ダウンロード後に再アップロード）、既存の ClickUp 添付ファイル URL（再アップロードせずに埋め込み）。

注意事項：

• base64 よりパスを優先してください。 パスは数トークンで済みますが、同じスクリーンショットを data: URI にすると、リクエストでファイルサイズのおよそ 4/3 の容量を消費します。
• キャプションが添付ファイル名になります。 ClickUp では画像の下にそのファイル名が表示されるため、読みやすいキャプションを付けてください。
• 番号付きリスト内の画像は ClickUp の番号付けを崩します。 上記のように、画像を間に挟んだ太字の行で手順を書いてください。
• アップロードされるのは実際の PNG／JPEG／GIF／WebP ファイルのみです。拡張子ではなく、コンテンツがチェックされます。ファイルの検証に失敗すると、書き込みは中止されます。addComment、editComment、updateTask はすべての無効な参照を報告し、何も変更しないため、重複を作成せずに Markdown を修正して呼び出しを再試行できます。createTask はタスクの作成前に画像を検証します。その後にアップロードが失敗した場合は、その時点でタスクがすでに存在するため、警告としてのみ報告されます。
• 添付ファイルは常にタスクに紐付くため、この方法ではドキュメントページにアップロード画像を埋め込めません。

パフォーマンスと制限事項

AI ワークフロー向けに最適化：

• スマートな画像処理：件数（MAX_IMAGES、既定値：4）とレスポンス全体のサイズ上限（MAX_RESPONSE_SIZE_MB、既定値：1MB）の両方を守りながら、最新の画像を優先するインテリジェントなサイズ調整
• 検索範囲：レート制限を回避するため、直近の 1000～3000 件のタスクを検索します（正確な件数はエンドポイントによって異なります）。
• 検索結果：エージェントに結果を過剰に提示しないよう、関連性の高い一致を最大 50 件まで返します。

現在の対象範囲：

• ワークスペース全体の一括管理ではなく、タスクレベルの操作に重点を置いています
• データ移行ではなく、会話型 AI ワークフロー向けに最適化されています
• 管理操作ではなく、生産性の向上を目的として設計されています

これらの制限により、開発コンテキストと生産性管理の両方で最も一般的なユースケースに対応しながら、信頼性の高いパフォーマンスを実現します。

ライセンス

MIT