ClickUp MCP Server について
ClickUp MCP Server は、Personal API Token を用いて AI アシスタントを ClickUp ワークスペースに接続する、Stdio 方式の MCP サーバーです。アシスタントとの会話から ClickUp のタスク、スペース、ドキュメントを管理したい利用者向けです。
主な機能
- 01タスクの作成と更新
- 02チーム、スペース、フォルダ、リストの管理
- 03カスタムフィールド値の読み取りと設定
- 04Doc ページの作成、編集、検索
- 05ビューの管理とビュー内タスクの取得
活用シーン
- 01AI アシスタントによる ClickUp リストへの複数タスクの一括作成
- 02ワークスペース構造の照会とスペース・フォルダの整理
- 03ClickUp Doc の内容を Markdown で読み書き
MCP 対応
本プロジェクトは MCP サーバーであり、ClickUp のタスク、スペース、フォルダ、フィールド、ドキュメント、ビューの操作を MCP クライアントへツールとして公開します。
設定
ローカルサーバーの設定はどのクライアントでも共通です。コピーしてクライアントの MCP 設定ファイルに貼り付けてください。
ツール
ローカルサーバーのツールはマシン上で起動して初めて取得できます。メンテナーはまだツール一覧を提供していません。
詳細
ClickUp MCP Server
ClickUp との連携を実現し、AI アシスタントが ClickUp ワークスペースを操作できるようにする、Model Context Protocol サーバーの実装です。
このサーバーは、MCP クライアントから呼び出されると、MCP 仕様に従って Stdio 経由で実行されます。
クイックスタート
このサーバーでは、認証に ClickUp Personal API Token を使用します。
- Personal API Token を生成します： ClickUp の設定で、「My Settings」>「Apps」に移動し、トークンを生成します。
- MCP クライアント（例：Claude for Desktop）を設定します： クライアント用にサーバーを設定する際、必要な環境変数を設定します。
MCP クライアントの設定例：
{
"mcpServers": {
"clickup": {
"command": "npx",
"args": ["@nazruden/clickup-server"],
"env": {
"CLICKUP_PERSONAL_TOKEN": "your_personal_api_token_here"
}
}
}
}
- MCP クライアントを再起動します。
必要に応じて、MCP クライアントがサーバーを自動的にダウンロードして起動します。
Smithery 経由でのインストール
Smithery 経由で ClickUp MCP Server を Claude Desktop に自動的にインストールするには：
npx -y @smithery/cli install @Nazruden/clickup-mcp-server --client claude
環境変数
必須
CLICKUP_PERSONAL_TOKEN：ClickUp Personal API Token です。サーバーが ClickUp API で認証するために必須です。
任意
LOG_LEVEL：サーバーのログレベルです。error、warn、info、debugをサポートしています。デフォルトはinfoです。ENCRYPTION_KEY：永続的な 32 バイトの 16 進数エンコードキーです。設定システム（src/config/app.config.ts）がこのキーを読み込むか生成し、src/security.tsに暗号化／復号化関数が含まれています。ただし、この仕組みは 現在、ClickUpServiceの Personal API Token 認証フローでCLICKUP_PERSONAL_TOKENを暗号化するためには使用されていません。PORT：サーバーのポートです。デフォルトの Stdio MCP サーバーモードでは 使用されません が、HTTP トランスポートや追加の HTTP 機能（独立したヘルスチェックエンドポイントなど）が明示的に追加された場合は関係する可能性があります。設定で読み込まれる場合、デフォルトは3000です。
利用可能なツール
現在、以下の MCP ツールが実装されています。
タスク管理
clickup_create_task：ClickUp リストに新しいタスクを作成します。- 必須：
list_id、name。 - 任意：
description、status、priority、assignees、due_date、time_estimate、tags。
- 必須：
clickup_update_task：既存のタスクのプロパティを更新します。- 必須：
task_id。 - 任意：書き込み可能な
ClickUpTaskプロパティ。
- 必須：
チームとリストの管理
clickup_get_teams：アクセス可能なすべてのチーム（ClickUp API v2 におけるワークスペース）を取得します。clickup_get_lists：特定のフォルダー内のすべてのリストを取得します。- 必須：
folder_id。
- 必須：
ボード管理
clickup_create_board：ClickUp スペースに新しいボードを作成します。- 必須：
space_id、name。
- 必須：
スペース管理
clickup_get_spaces：指定したワークスペース（チーム）のすべてのスペースを取得します。- 必須：
team_id（ワークスペース ID）。 - 任意：
archived（ブール値、デフォルトはfalse）。
- 必須：
clickup_create_space：ワークスペース内に新しいスペースを作成します。- 必須：
team_id（ワークスペース ID）、name。 - 任意：
multiple_assignees（ブール値）、features（due_dates、time_trackingなどの機能フラグを含むオブジェクト）。
- 必須：
clickup_get_space：特定のスペースの詳細を取得します。- 必須：
space_id。
- 必須：
clickup_update_space：既存のスペースを更新します。- 必須：
space_id。 - 任意：
name、color、private、admin_can_manage、archived、features。
- 必須：
clickup_delete_space：スペースを削除します。- 必須：
space_id。
- 必須：
フォルダー管理
clickup_get_folders：指定したスペース内のすべてのフォルダーを取得します。- 必須：
space_id。 - 任意：
archived（ブール値、デフォルトはfalse）。
- 必須：
clickup_create_folder：スペース内に新しいフォルダーを作成します。- 必須：
space_id、name。
- 必須：
clickup_get_folder：特定のフォルダーの詳細を取得します。- 必須：
folder_id。
- 必須：
clickup_update_folder：既存のフォルダーを更新します。- 必須：
folder_id、name。
- 必須：
clickup_delete_folder：フォルダーを削除します。- 必須：
folder_id。
- 必須：
カスタムフィールド管理
clickup_get_custom_fields：指定したリストでアクセス可能なすべてのカスタムフィールドを取得します。- 必須：
list_id。
- 必須：
clickup_set_task_custom_field_value：特定のタスクのカスタムフィールドに値を設定します。- 必須：
task_id、field_id、value。 - 任意：
value_options（オブジェクト。日付フィールドの場合は{ "time": true }など）。
- 必須：
clickup_remove_task_custom_field_value：特定のタスクのカスタムフィールドの値を削除／クリアします。- 必須：
task_id、field_id。
- 必須：
ドキュメント管理
注： ClickUp の Docs API（特に v2。一部の操作では v3 が使われるようになっています）には制限があります。コンテンツは主に Markdown として扱われます。高度な書式設定や複雑な埋め込みは、完全にはサポートされない場合があります。ClickUp の V3 /docs エンドポイントでは、現在 API 経由でドキュメントを直接削除することはサポートされていません。アーカイブやページ操作を通じて Docs のライフサイクルを管理してください。
clickup_search_docs：ワークスペース（チーム）内の Docs を検索します。- 必須：
workspace_id。 - 任意：
query（文字列）、include_archived（ブール値）。
- 必須：
clickup_create_doc：新しい Doc を作成します。- 必須：
workspace_id、name。 - 任意：
parent（idとtypeを含むオブジェクト）、visibility（文字列：「private」、「workspace」、「public」）、create_page（ブール値）。
- 必須：
clickup_get_doc_pages：特定の Doc 内のページ一覧を取得します。- 必須：
doc_id。
- 必須：
clickup_create_doc_page：特定の Doc 内に新しいページを作成します。- 必須：
workspace_id、doc_id、name（ページタイトル）。 - 任意：
content（Markdown）、orderindex（数値。ただし、v3 API では使用されない場合があります）、parent_page_id（文字列）、sub_title（文字列）、content_format（文字列）。
- 必須：
clickup_get_doc_page_content：特定の Doc ページのコンテンツ（Markdown）を取得します。- 必須：
workspace_id、doc_id、page_id。 - 任意：
content_format（文字列）。
- 必須：
clickup_edit_doc_page_content：特定の Doc ページのコンテンツおよび／またはタイトルを更新します。- 必須：
workspace_id、doc_id、page_id、content（Markdown）。 - 任意：
title（文字列。API のnameに対応）、sub_title（文字列）、content_edit_mode（文字列：「replace」、「append」、「prepend」）、content_format（文字列）。
- 必須：
ビュー管理
clickup_get_views：指定した親リソース（Team、Space、Folder、List）のすべてのビューを取得します。- 必須：
parent_id（親リソースの ID）、parent_type（文字列：「team」、「space」、「folder」、または「list」）。
- 必須：
clickup_create_view：Team、Space、Folder、List 内に新しいビューを作成します。- 必須：
parent_id、parent_type、name（文字列：新しいビューの名前）、type（文字列：ビューの種類。例：「list」、「board」、「calendar」、「gantt」）。 - 任意：
grouping、divide、sorting、filters、columns、team_sidebar、settings（ビューの設定を定義するオブジェクト）。
- 必須：
clickup_get_view_details：特定のビューの詳細を取得します。- 必須：
view_id。
- 必須：
clickup_update_view：既存のビューを更新します。- 必須：
view_id。 - 任意：
name（文字列）、grouping、divide、sorting、filters、columns、team_sidebar、settings。
- 必須：
clickup_delete_view：ビューを削除します。- 必須：
view_id。
- 必須：
clickup_get_view_tasks：特定のビューに属するタスクを取得します。- 必須：
view_id。 - 任意：
page（数値：ページネーション用の 0 始まりのページ番号）。
- 必須：
開発
-
リポジトリをクローンします：
git clone <repository_url> cd clickup-mcp-server -
依存関係をインストールします：
npm install -
ルートディレクトリに
.envファイルを作成し、CLICKUP_PERSONAL_TOKENを追加します：CLICKUP_PERSONAL_TOKEN=your_actual_personal_api_token_here LOG_LEVEL=debug -
開発モード（Stdio）で起動します： サーバーは stdin/stdout で MCP メッセージを受信します。
npm run devこれにより、
ts-node-devを使ってsrc/index.tsが実行されます。 -
本番用にビルドします：
npm run buildTypeScript が
dist/にコンパイルされます。 -
テストを実行します：
npm testsrc/__tests__にある Jest のユニットテストが実行されます。.env.testファイルがあることを確認してください（src/__tests__/setup.tsを参照）。
MCP Inspector を使ったテスト
MCP Inspector を使って、サーバーをローカルでテストできます：
CLICKUP_PERSONAL_TOKENを利用できる状態にします。次のいずれかの方法を使えます：- Inspector を実行する前に、シェル環境に設定します。
- MCP Inspector にサーバー環境変数の設定オプションがある場合は、MCP Inspector の UI で設定します。
- ローカルの
.envファイルに設定します（src/index.tsがdotenvを読み込みます）。
- サーバーとともに Inspector を実行します：
Inspector の UI が起動し、サーバーに接続してそのツールを呼び出せるようになります。npx @modelcontextprotocol/inspector node --loader ts-node/esm src/index.ts
セキュリティ
- ClickUp Personal API Token を使って認証します。このトークンは安全に保管し、他者に知られないようにしてください。 パスワードと同様に扱ってください。
- サーバーは、利用する MCP クライアントまたは開発環境から環境変数を介して
CLICKUP_PERSONAL_TOKENが提供されることを想定しています。 - 設定システムには
ENCRYPTION_KEY用のロジックが含まれており、src/security.tsには暗号化関数がありますが、ClickUpServiceでは Personal API Token に対して現在適用されていません。 - デフォルトの
LOG_LEVEL=infoでは、トークンなどの機密データはログに記録されません。デバッグレベルでは、より詳細な情報が記録される場合があります。 - ClickUp API 呼び出しのレート制限には、残りのリクエスト数をログに記録することで対応します（
ClickUpServiceを参照）。
トラブルシューティング
よくある問題
-
認証エラー（ClickUp API からの 401）
CLICKUP_PERSONAL_TOKEN環境変数が正しく設定され、サーバープロセスからアクセスできることを確認してください。- トークンが有効で、ClickUp の設定で取り消されていないことを確認してください。
- 認証に関する
ClickUpServiceのメッセージがサーバーログにないか確認してください。
-
ClickUp API によるレート制限
- サーバーは、ClickUp API のレスポンスに含まれるレート制限情報をログに記録します。
- レート制限に頻繁に達する場合は、使用量が多いことを示しています。サーバー自体は、
axiosのデフォルトの動作を超えるキューイングや複雑なバックオフは実装していません。
-
サーバーが起動しない／MCP Inspector の接続に関する問題
CLICKUP_PERSONAL_TOKENが設定されていることを確認してください。npm run devを使用している場合は、コンソールで TypeScript またはts-node-devのエラーを確認してください。node --loader ts-node/esm src/index.tsで MCP Inspector を使用している場合は、ts-nodeとプロジェクトの依存関係が正しくインストールされていることを確認してください。src/index.tsまたはClickUpServiceからのコンソールエラーを確認してください。
サーバーログの確認
npm run devまたはnpm startで実行すると、ログはコンソールに出力されます。- MCP クライアント（Claude for Desktop など）から実行した場合、ログは通常そのクライアントによって管理されます。Claude for Desktop のログは、通常、次の場所で確認できます。
- Windows：
%USERPROFILE%\AppData\Local\Claude\Logs\mcp\<server_name_and_id>\<process_id>.log（パスは多少異なる場合があります） - macOS：
~/Library/Logs/Claude/mcp/<server_name_and_id>\<process_id>.log（パスは多少異なる場合があります）
- Windows：
サポート
このプロジェクトがお役に立ちましたら、継続的な開発とメンテナンスを支援するため、コーヒーをごちそうしていただけると幸いです。
ライセンス
MIT ライセンス - 詳細は LICENSE ファイルをご覧ください
テストパイプラインの修正
コメント
AI アプリケーションが外部のツールやデータソースに統一的な方法で接続するためのオープンなプロトコルです。クライアントはモデルとの対話を担い、MCP サーバーはツール・リソース・プロンプトテンプレートを提供します。標準メッセージでやり取りするため、1 つのサーバーを複数のクライアントで再利用できます。