ClickUp MCP Server（セルフホスト版）

あなた専用の ClickUp MCP サーバーです。Railway にデプロイすると、Hermes Agent などの AI から、あなたの ClickUp ワークスペースを直接操作できるようになります。

• ✅ タスク・リスト・フォルダ・スペースの作成／取得／更新／削除

• ✅ コメント、タグ、依存関係、タスクリンク

• ✅ 時間計測（タイムトラッキング）、ステータス滞在時間レポート

• ✅ メンバー検索、チャット、ClickUp Docs

• ✅ 全 51 ツールを MCP 経由で利用可能

通信方式は SSE（Server-Sent Events）。各ユーザーが自分専用のインスタンスをデプロイし、自分の ClickUp トークンを環境変数で渡す方式です。

⚠️ 重要なセキュリティ注意 このサーバーはデフォルトでは認証がありません。デプロイした URL（https://xxx.up.railway.app）を知っている人は、あなたの ClickUp を操作できてしまいます。 デプロイURLは他人に共有・公開しないでください。 各自が自分用に1つずつデプロイして使うのが前提です。 さらに安全にしたい場合は、後述の （任意）アクセス認証を有効にする で合言葉（Bearerトークン）を設定すると、URLが漏れても接続を防げます。配布・本番運用では設定を強く推奨します。

📋 全体の流れ（5ステップ）

1. ClickUp の API トークンを取得
2. この GitHub リポジトリを Fork（または Clone）
3. Railway にデプロイ
4. Railway の環境変数に CLICKUP_API_TOKEN を設定
5. Hermes Agent に MCP を追加して接続

所要時間の目安：10〜15分。プログラミングの知識は不要です。

Related MCP server: clickup-mcp

ステップ 1：ClickUp API トークンを取得する

このトークンが「AIがあなたのClickUpにアクセスするための鍵」になります。

1. ClickUp にログインします。

2. 画面**右上のアバター（自分のアイコン）**をクリック。

3. Settings（設定） を開きます。

4. 左メニューの一番下あたりにある Apps をクリック。

5. API Token の項目で Generate（生成） ボタンを押します。

6. pk_ で始まる文字列が表示されます。これがあなたのトークンです。 「Copy」を押してコピーし、メモ帳などに一時保存しておいてください。

🔒 このトークンはパスワードと同じです。他人に見せたり、SNSやGitHubに貼り付けたりしないでください。

ステップ 2：GitHub でリポジトリを Fork する

「Fork」とは、この公開リポジトリを自分のGitHubアカウントにコピーすることです。 こうすることで、後で Railway がそのコードを読み取ってデプロイできます。

1. GitHub のアカウントを持っていない場合は、まず無料登録します。

2. このリポジトリのページを開きます。

3. 画面右上の「Fork」ボタンをクリック。

4. 「Create fork」を押すと、あなたのユーザー名/clickup-mcp-dist という名前で自分のコピーが作成されます。

💡 Git に詳しい人は Clone でもOKですが、Railway 連携には Fork が一番簡単です。

ステップ 3：Railway にデプロイする

Railway は、コードを自動でサーバーとして公開してくれるサービスです。無料枠から始められます。

1. Railway にアクセスし、**「Login」→「Login with GitHub」**でログインします。 （GitHub アカウントでそのままログインできます）

2. ダッシュボードで 「New Project（新規プロジェクト）」 をクリック。

3. 「Deploy from GitHub repo」 を選択します。

4. 初回は「Configure GitHub App」で Railway に GitHub へのアクセスを許可します。 ステップ2でForkした clickup-mcp-dist リポジトリを選べるようにします。

5. リポジトリ一覧から clickup-mcp-dist を選択します。

6. Railway が自動的にビルド（npm run build）と起動（npm start）を始めます。

この時点ではまだトークンが無いので起動に失敗します。問題ありません。次のステップで設定します。

ステップ 4：環境変数 CLICKUP_API_TOKEN を設定する

ステップ1で取得したトークンを Railway に登録します。

1. Railway のプロジェクト画面で、デプロイしたサービス（四角いカード）をクリック。

2. 上部のタブから 「Variables（変数）」 を開きます。

3. 「New Variable」 をクリックし、次のように入力します。

   • Variable name（名前）：CLICKUP_API_TOKEN

   • Value（値）：ステップ1でコピーした pk_... のトークン

4. 「Add」 で保存します。

5. 保存すると Railway が自動で再デプロイを始めます。 「Deployments」 タブのログに次のように出れば成功です：

   🔑 ClickUp API トークンを読み込みました (length: 43)
   🚀 ClickUp MCP Server is running on port ...

公開URL（ドメイン）を発行する

6. 「Settings」 タブ → 「Networking」 → 「Generate Domain」 をクリック。

7. ポート番号の入力を求められたら 8080 と入力してください。 （Railway が内部で割り当てる標準ポートが 8080 のため。これで正しくルーティングされます）

8. https://clickup-mcp-dist-production-xxxx.up.railway.app のような URL が発行されます。 この URL を控えておきます。これがあなたのMCPサーバーのアドレスです。

💡 補足：本サーバーは環境変数 PORT（Railwayが自動で渡す）を見て待ち受けます。 Railway の標準値が 8080 のため、Generate Domain でも同じ 8080 を指定すれば一致します。

動作確認

9. ブラウザでその URL を開いて、ClickUp MCP Server is running! と表示されれば成功です。🎉

ステップ 5：Hermes Agent に MCP を追加する

下記の設定の 【あなたのRailwayドメイン】 と ${CLICKUP_MAMORU_AUTH} を、あなたの実際のドメインとAuth トークンに書き換えて、そのまま Hermes Agent に渡し、「この MCP サーバーを追加して」 と指示してください。

mcp_servers:
  clickup-mamoru:
    command: npx
    args:
      - -y
      - mcp-remote
      - https://【あなたのRailwayドメイン】.up.railway.app/sse
      - --header
      - "Authorization:${CLICKUP_MAMORU_AUTH}"
    timeout: 60

• 【あなたのRailwayドメイン】 … ステップ4で発行したURLのドメイン部分に置き換える

• ${CLICKUP_MAMORU_AUTH} … あなたの Auth トークン（Bearer + 合言葉）に置き換える （合言葉は、後述のアクセス認証で Railway に設定した MCP_AUTH_TOKEN の値）

💡 お使いのPCに Node.js（v20以上） が必要です（npx を使うため）。 設定後、Hermes で /reset を実行すると反映されます。「私のClickUpのワークスペース一覧を見せて」と頼み、get_workspaces が動けば接続成功です。

🔐 （任意）アクセス認証を有効にする

デフォルトでは、URLを知っている人なら誰でも接続できてしまいます。 **合言葉（Bearerトークン）**を設定すると、その合言葉を持つクライアントだけが接続でき、URLが漏れても安全になります。配布・本番運用では設定を強く推奨します。

サーバーに合言葉(MCP_AUTH_TOKEN)を設定
   → 接続時に Authorization: Bearer <合言葉> が一致しないと 401 で拒否

CLICKUP_API_TOKEN（ClickUpの鍵）とは別物の、サーバー入口専用の鍵です。

手順 1：合言葉を生成する

長くてランダムな文字列を用意します（推測されにくいもの）。例：

# Mac / Linux
openssl rand -hex 32

# Windows (PowerShell 5.1 / 7 どちらでも動作)
-join ((1..32) | ForEach-Object { '{0:x2}' -f (Get-Random -Maximum 256) })

上記が使えない環境では、簡易な代替として PowerShell で [guid]::NewGuid().ToString('N') でも32文字の合言葉を生成できます。

生成された文字列をコピーしておきます。

手順 2：Railway に環境変数を追加する

1. サービスの 「Variables」 タブを開く

2. New Variable で

   • Name: MCP_AUTH_TOKEN

   • Value: 手順1で生成した合言葉

3. 保存 → 自動で再デプロイ

4. ログに次が出れば有効化成功：

   🔒 アクセス認証が有効です (MCP_AUTH_TOKEN length: ...)

手順 3：クライアント側に合言葉を渡す

ステップ5の ${CLICKUP_MAMORU_AUTH} を、Bearer + 手順1の合言葉に書き換えて Hermes に渡します。

例：合言葉が bfe60fec...ec78 なら、Authorization: の値は Bearer bfe60fec...ec78（Bearer と合言葉の間は半角スペース1つ）になります。

⚠️ サーバー側 MCP_AUTH_TOKEN と、クライアント側 Bearer の後ろの値は完全に一致させてください。一致しないと 401 Unauthorized、または tools/list（接続テスト）は通るのに実行時にタイムアウト/切断します。

🛠️ （上級者向け）ローカルPCで動かす場合

Railway を使わず、自分のPCで直接動かすこともできます。

# 1. リポジトリを取得
git clone https://github.com/【あなたのユーザー名】/clickup-mcp-dist.git
cd clickup-mcp-dist

# 2. 依存パッケージをインストール
npm install

# 3. 環境変数ファイルを作成し、トークンを記入
#   Mac/Linux:
cp .env.example .env
#   Windows (PowerShell):
#   Copy-Item .env.example .env
#   → エディタで .env を開き CLICKUP_API_TOKEN=pk_xxx を記入

# 4. ビルドして起動
npm run build
npm start

起動後、MCP設定の URL を http://localhost:3000/sse にすればローカル接続できます。

利用可能なツール一覧（全51種）

❓ トラブルシューティング

ライセンス

MIT License — 自由に利用・改変・再配布できます。

謝辞

Model Context Protocol および ClickUp API を利用しています。