ClickUp MCP サーバー

ClickUp 用の Model Context Protocol サーバー。2つの考え方を軸に作られています。

すべてが人間の名前を使う。 find(scope: "Cavalry/Findings", assignee: "me", due: "overdue") — ID は不要、ID を見つけるためにツリーを辿る必要もありません。解決できない名前は、有効な選択肢を列挙したエラーを返します。自信満々の空結果は失敗より悪いからです。

何ができるかはあなたが選ぶ。 4つの能力プロファイルがあり、すべての送信リクエストで強制されます。無人エージェントに agent プロファイルを与えれば、タスクやコメントの作成はできますが、既存のものを変更・削除することはできません。

18ツール、354テスト。バージョン 4.3.0 — CHANGELOG.md を参照。nsxdavid/clickup-mcp-server の大幅に改修されたフォークです。

ステータス: 4.x は新しいものです。5回の敵対的レッドチームラウンドを経ていますが、まだ本番稼働していません。以前の 3.x 系はこのリポジトリに引き続き同梱されており、参照デプロイメントが実行しているのは今もそちらです — 3.x の実行 を参照してください。

クイックスタート

ClickUp → Settings → Apps → API Token からトークンを取得します（pk_ で始まります）。ワークスペースは自動的に検出されます — 他に設定するものはありません。

インストール不要:

{
  "mcpServers": {
    "clickup": {
      "command": "npx",
      "args": ["-y", "github:benthesoundguy/clickup-mcp-server"],
      "env": { "CLICKUP_API_TOKEN": "pk_your_token_here" }
    }
  }
}

またはクローンから — 何かを変更する予定があるならこちらがおすすめです:

git clone https://github.com/benthesoundguy/clickup-mcp-server
cd clickup-mcp-server
npm install          # builds automatically
npm run check        # verifies the token and connects — do this before wiring up a client

{
  "mcpServers": {
    "clickup": {
      "command": "node",
      "args": ["/absolute/path/to/clickup-mcp-server/build/v4/index.js"],
      "env": { "CLICKUP_API_TOKEN": "pk_your_token_here" }
    }
  }
}

そのブロックの置き場所

上記の形は Claude Desktop、Claude Code、Cursor、Cline、Windsurf でそのまま使えます — いずれも mcpServers キーを使用します。2つのクライアントだけが異なります:

• VS Code (.vscode/mcp.json) は mcpServers の代わりに servers を使用します。内部の形は同じです。Cursor の設定をそのままコピーするのが最も多い設定ミスです。

• Zed (settings.json) は context_servers を使用し、コマンドをネストします:

  { "context_servers": { "clickup": { "command": { "path": "node", "args": ["/path/to/build/v4/index.js"] } } } }

Claude Code はファイルを完全に省略できます:

claude mcp add clickup --env CLICKUP_API_TOKEN=pk_... -- npx -y github:benthesoundguy/clickup-mcp-server

トークンをファイルに入れる場合

クライアント設定にトークンを貼り付けたくない場合 — デスクトップアプリは設定ファイルを書き換え、古いコピーを保持し続けることがあります — インストール先の隣に .env を置き、env ブロックを完全に省略します:

echo 'CLICKUP_API_TOKEN=pk_your_token_here' > .env

サーバーは <cwd>/.env、<install>/.env、<install>/../.env の順に探し、起動時にどれを使ったかを表示します。ファイルのトークンは環境変数より優先されるため、片方でローテーションすれば実際に反映されます。他のすべての設定は逆の順序で動作します — クライアント設定の明示的な値が常に優先されるため、紛れ込んだ .env が MCP_PROFILE を広げることは決してありません。サーバーに MCP_STRICT_ENV=1 を設定すると、ルックアップ全体をオフにできます。

動かないとき

npm run check          # from a clone
node build/v4/index.js --check

これは、サーバーが解決したすべての入力を表示します — 見つけた .env と適用した内容、トークンが存在し正しい形かどうか、アクティブなプロファイルとツール数、Node のバージョンとビルドスタンプ — そして実際に ClickUp に接続し、あなたが誰かとレート制限の予算を報告します。トークンは決して表示されないため、出力はそのまま issue に貼り付けても安全です。

トークンがない場合、サーバーは stdio モードで静かに死ぬことはありません。起動し、ツールを登録し、すべての呼び出しが何が問題でどう直すかを答えるため、問題は探しに行かなければならないログファイルではなく、会話の中で明らかになります。（HTTP モードでは依然として 1 で終了します — 無人デプロイメントは大きな音を立てて失敗すべきです。）

Related MCP server: ClickUp MCP Server

能力プロファイル

1つのバイナリ、4つのプロファイル、MCP_PROFILE で選択します。一度インストールし、プロファイルごとにクライアントエントリを追加して、各エージェントに持たせたい能力を有効にします。

スキーマコストとは、ツール定義がすべてのリクエストで、実際の作業の前にモデルのコンテキストで消費する量です。比較として、3.x は88ツールで ~18,600トークンです。

agent が興味深いものです。 追加はできても変更・破壊は決してできないため、無人エージェントが最悪やっても、あなたが削除できる散らかりを作るだけです。その保証は3つの層で強制され、セキュリティ境界となるのは3番目だけです:

1. ツールフィルタリング — どのツールが表示されるか (コンテキストコスト + ツール選択)

2. アクションフィルタリング — ツールが宣伝するアクション (コンテキストコスト + 正直さ)

3. 書き込みポリシー — アップロードを含むすべての送信リクエストでチェックされる許可リスト ← 保証

層1と2は、すべてのツールが将来のすべての貢献者によって正しくタグ付けされていることに依存します。層3は依存しません: 実際のリクエストを送信時に検査するため、タグ付けを間違えたツール、リファクタリング、来年追加されるエンドポイントがプロファイルを広げることはできません。テストスイートは、agent コンテキストで core 専用ハンドラを直接呼び出すことでこれを証明しています — 層1と2を完全にバイパスし — ワイヤーに何も到達しないことを検証します。

追加的に見えるが agent から意図的に除外されているもの: タグの付与、カスタムフィールドの設定、依存関係の追加はすべて既存のタスクを変更します。ウェブフックの作成は、ワークスペースデータを外部エンドポイントにストリーミングし始めます。追加のみと安全は同じ性質ではありません。

デフォルトが core で full でない理由

full はメンバーシップ管理を許可します — ユーザーの招待は課金対象シートを消費し、削除は実在する人のアクセスを変更します — さらに、ワークスペースデータを外部に送信するウェブフックも含みます。どれも最初の接続のためのものではなく、誰も変更しないデフォルトは安全なものでなければなりません。管理を望むなら名前を指定して要求してください。それまでは、拒否メッセージが正確にその方法を教えてくれます。

添付ファイルとファイルシステム

attach はサーバーが実行されているマシン上のファイルを読み取ります。これは書き込みポリシーが確認できないリソースです — URL を検査しますが、ファイル読み取りには URL がありません — そのため CLICKUP_ATTACH_ROOT によって別途管理されます:

• 設定あり → 読み取りはそのディレクトリに制限されます。包含は .. とすべてのシンボリックリンクを解決した後のファイルの実際のパスに対してチェックされます。

• 未設定 → core と full はプロセスがアクセスできる任意のファイルを読み取れます。agent では、attach はまったく提供されません（13ツールではなく12ツール）。安全なデフォルトルートがないためです: 作業ディレクトリは通常プロジェクトディレクトリであり、そこに .env があります。

設定ミスのあるルートは起動時に無視されるのではなく致命的になります — 静かに存在しない境界は、ないより悪いからです。

ツール

ツールは、意味がある場合は消えるのではなく狭くなります: read では、comment は読み取り引数のみを表示し、checklist は list のみを宣伝します。これにより、スキーマは拒否されるアクションを宣伝するのではなく、この接続で何ができるかの真実を伝えます。

すべてが従うルール

自信満々の間違った答えを決して返さない。 ClickUp はこれを間違えやすくします。なぜなら、不正な入力に対して陽気なナンセンスで答えるからです:

そこでこのサーバーは名前を解決し、曖昧さではエラーを発生させます（4つのリストに一致する "Findings" は、コイン投げではなく4つすべてを列挙するエラーになります）; フィルタ値が解決しない場合は空を返すのではなくエラーを発生させ; enum をリストが実際に受け付けるものに対してクライアント側で検証し; 信頼できない書き込みをオブジェクトを読み戻して検証し; 数を過大報告することは決してありません — ページングを停止したクエリは 100+ matches を報告し、クライアント側フィルタは実際にスキャンした量を報告します。

エラーは何が失敗したか、なぜか、次に何をすべきかを、有効な選択肢を列挙して示します。

環境変数

リモートモード（Claude web + モバイル、および任意の HTTP クライアント）

サーバーはストリーミング可能な HTTP を話し、3つの独立した認証情報を受け付ける。いずれか1つでリクエストを認証でき、それらは共存することを意図している。なぜなら、異なるクライアントが異なるものを提示できるからだ。

MCP_TRANSPORT=http MCP_AUTH_TOKEN=$(openssl rand -hex 24) \
MCP_PROFILE=core CLICKUP_API_TOKEN=... node build/v4/index.js

GET /health は認証不要のプローブで、バージョン、アクティブなプロファイル、ツール数、添付ルートを報告する。

OAuth（ホスト型クライアントが求めるもの）

このサーバーは OAuth プロバイダーである必要はなく、実際そうではない。 2025-06-18 の MCP 仕様以降、MCP サーバーはリソースサーバーである：信頼する認可サーバーを指定し、そのサーバーが発行するトークンを検証する。ログイン、同意、トークン発行はあなたの IdP — Cloudflare Access、WorkOS、Auth0、Descope、Stytch、Keycloak、OIDC ディスカバリーを持つあらゆるもの — に属する。

MCP_TRANSPORT=http \
MCP_PUBLIC_URL=https://mcp.example.com \
MCP_OAUTH_ISSUER=https://your-idp.example.com \
CLICKUP_API_TOKEN=pk_... node build/v4/index.js

それが設定のすべてだ。その後サーバーは：

• /.well-known/oauth-protected-resource で RFC 9728 保護リソースメタデータを提供し、あなたの発行者を認証なしで公開する；

• 認証なしのリクエストに 401 と、そのドキュメントを指す WWW-Authenticate ヘッダーで応答する。これがクライアントがログイン先を発見する方法だ；

• /.well-known/openid-configuration（または RFC 8414）経由で発行者の署名鍵を発見する。または、設定した場合は MCP_OAUTH_JWKS_URL を使用する；

• すべてのトークンを検証する：RS256 固定、発行者の JWKS に対する署名、exp、nbf、iss、そして aud — トークンはこのサーバーを名指ししなければならない。

最後のチェックが重要だ。これがないと、あなたの IdP が他のサービスのために発行したトークンがここで再利用される可能性がある。MCP_PUBLIC_URL が推測ではなく必須である理由はこれだ：期待される audience はリクエストから取得してはならない。なぜなら Host ヘッダーは呼び出し元が設定するからだ。

発行者が設定されると MCP_AUTH_TOKEN は任意になる — OAuth のみのデプロイでは、決して使われない共有パスワードは不要だ。

動的クライアント登録に関する注記。 2026-07-28 の仕様は DCR を廃止し、クライアント ID メタデータドキュメントを採用した。この変更は認可サーバーとクライアントに影響する。リソースサーバーはどちらの場合も影響を受けない。これは、独自の AS を構築するよりも委任する正当な理由だ。

claude.ai コネクタの注意点

Claude のカスタムコネクタ UI は OAuth フィールドのみを受け付ける — Authorization URL、Token URL、Client ID、Client Secret。静的ベアラートークンやカスタムヘッダー用のフィールドはない（#112、#411）。つまり：

• OAuth が設定されている場合、通常のカスタムコネクタとして接続する。これが意図された経路だ。

• OAuth がない場合、唯一の方法は URL 内トークン形式 /mcp/<token> で、MCP_ALLOW_TOKEN_IN_PATH=1 で有効になる。動作はするが、プロキシがログに記録する URL に資格情報を置くことになり、strict モードがこれを拒否する理由だ。回避策として扱い、デプロイ方法としては扱わないこと。

Cloudflare Access（任意の第3の認証モード）

CF_ACCESS_TEAM_DOMAIN と CF_ACCESS_AUD を設定すると、サーバーは Access が転送するすべてのリクエストに付与する Cf-Access-Jwt-Assertion ヘッダーを検証する：チーム JWKS に対する RS256、さらに exp、iss、aud。両方の Access フローが1つの経路で検証される — ブラウザログインは email を運び、サービス トークンは common_name を運ぶ。

これは多層防御だ。Access を通らずにオリジンに到達するリクエスト — トンネルの設定ミス、2番目の入口、ホストのネットワーク上の何か — は、Access 認証済みの呼び出し元を偽装できない。フェイルクローズする：alg は RS256 に固定され（alg: none や HS256 の混乱は拒否される）、到達不能な JWKS はバイパスではなく拒否となり、JWKS URL は設定から取得され、トークンから取得されることは決してない。

ベアラー認証は引き続き機能する。 有効な Access JWT または有効なベアラートークンによってリクエストは認可されるため、ヘッダー対応エージェントは変更を必要としない。

オリジンは /.well-known/oauth-* を提供しない — Managed OAuth が有効な場合、Access が認可サーバーとなり、エッジでディスカバリーを提供する。

strict モード（MCP_STRICT_ENV=1）

無人デプロイのための姿勢。シークレットは環境から取得されなければならず、サーバーは資格情報を発明したり永続化したりせず、設定ミスで起動する代わりに、実行可能なメッセージとともに終了コード 1 で終了する。また、プロキシのアクセスログに資格情報が残る URL パストークン形式も拒否する。

これは重要だ。.env ファイルの検索は意図的に process.env より優先される — デスクトップホストは終了時にメモリから独自の設定ファイルを書き換えるため、そこではファイルが優先されなければならない。サーバーではその優先順位は逆になる：作業ディレクトリに置かれた紛れ込んだ .env が、systemd ユニットを黙って上書きすることになる。strict モードはその検索を無効にする。

完全なレシピは deploy/DEPLOY.md を参照：VPS セットアップスクリプト、強化された systemd ユニット、Cloudflare トンネル、そして Claude への接続。

3.x からのアップグレード

ツール名は完全に異なる — 4.x はリネームではなく書き直しだ。ハードコードされた 3.x のツール名（保存済みプロンプト、エージェント指示、スクリプト）を保持しているものはすべて更新が必要だ。

対応関係はほとんどが多対一だ：

引き継がれないもの： project_intelligence（8つのローカル分析レポート）と reminders_create。ステータスの管理 — 作成、名前変更、並べ替え — も存在しない。meta はステータスを読み取るが変更はしない。これらが必要な場合は、3.x を実行すること。

3.x の実行

3.x は引き続きこのリポジトリからビルド・出荷されている：

npm run start:v3       # via the package script
node build/index.js    # the 3.x entry point directly

MCP クライアントを build/v4/index.js の代わりに build/index.js に向けて、引き続き使用する。

deploy/ 内の参照 systemd ユニットは意図的にまだ 3.x に固定されている。なぜなら、実行中のサービスは、パッケージのデフォルトがその下で移動したからといってメジャーバージョンを変更すべきではないからだ。ExecStart を build/v4/index.js に向け、MCP_PROFILE を明示的に設定して移行すること。

既知の ClickUp API の制限

ここでのバグではない — API に本当にこれらが欠けており、このサーバーは回避策を偽装するのではなく、その制限を報告する。

• タスクはリスト間で移動できません。 POST /list/{dest}/task/{id} は 200 を返し、「複数リストのタスク」ClickApp がない限り何も行いません。list_id を指定した PUT は黙って無視されます。/move は 404 になります。update の移動パスはタスクを読み戻して、移動が発生しなかった場合にエラーを報告します（黙って成功と報告するのではなく）。

• 添付ファイルにはリストエンドポイントがありません。 — task がタスクオブジェクトから読み取ります。アップロードはマルチパートのみで、25MB に制限されています。

• ドキュメント は名前の変更や削除ができず、ページも削除できません。

• カスタムフィールド定義 は一覧表示と作成のみ可能で、編集や削除はできません。

• 日付カスタムフィールドは Unix ミリ秒を必要とします。 YYYY-MM-DD は ClickUp によって拒否されます。タスクの due_date/start_date は両方を受け付け、ここで変換されます。

• ステータス名とタグ名は小文字で保存されます。 ここでは大文字小文字を区別せずに照合します。

• リストはスペースのステータスを頻繁に上書きします。 そのため「どのステータスが有効か」はリストごとの問題です。meta がリストごとに回答します。

• ClickUp は無効な enum に対して HTTP 500 で応答するため、enum は送信前にクライアント側で検証されます。

• レート制限は トークンあたり約 100 リクエスト/分 で、それを使用するすべての操作で共有されます。whoami が現在の残量を報告し、サーバーは x-ratelimit-* ヘッダーに基づいて自身のペースを調整します。

Webhook レシーバー（オプション）

外部インフラなしで ClickUp の Webhook イベントを処理します:

WEBHOOK_PORT=3001 WEBHOOK_SECRET=your_secret node build/webhook-receiver/index.js

• 生のリクエストボディに対する HMAC-SHA256 検証。シークレットが設定されている場合、署名のないリクエストは拒否されます。

• 構造化されたイベント解析 — タイプ、オブジェクト、操作、変更、ユーザー、タイムスタンプ。

• コールバック URL へのオプションの転送（WEBHOOK_FORWARD_URL）。

• 純粋な Node.js http、追加の依存関係はゼロ。

開発

npm install
npm run build
npm test          # 354 tests, mocked HTTP — no token needed
npm run smoke     # live CRUD walk (needs CLICKUP_API_TOKEN; creates and
                  # deletes its own sandbox in your workspace)

4.x のアーキテクチャノートは src/v4/README.md にあります。設計の根拠と測定結果は V4-PLAN.md にあります。

「動かなかった」修正のデバッグ

whoami を呼び出してください。実行中のビルドのバージョンとスタンプが報告されます。MCP ホストはセッション開始時に独自のサーバープロセスを起動して保持するため、再ビルドしても実行中のセッションには反映されません。スタンプが変更より古い場合は、ホストアプリを再起動してください。このツールが存在する前は、これが原因で何件も幽霊バグ報告が発生していました。

ライセンス

MIT — LICENSE を参照。元は nsxdavid/clickup-mcp-server のフォークで、作者は David Whatley です。