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

あなた専用の ClickUp MCP サーバーです。Railway にデプロイすると、Hermes Agent や Claude などの 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 / Claude に MCP 設定を追加して接続

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

Related MCP server: ClickUp MCP Server

ステップ 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-server という名前で自分のコピーが作成されます。

💡 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-server リポジトリを選べるようにします。

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

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-server-production-xxxx.up.railway.app のような URL が発行されます。 この URL を控えておきます。これがあなたのMCPサーバーのアドレスです。

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

動作確認

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

ステップ 5：AIクライアントに接続する

このサーバーは SSE で通信します。クライアント側は mcp-remote を使い、/sse を末尾に付けた URL に接続します。 お使いのPCに Node.js（v20以上） が必要です（npx を使うため）。

設定方法はクライアントによって異なります。下記から該当するものを選んでください。

• A. Hermes Agent（config.yaml を使う） … 👇このすぐ下

• B. Claude Desktop など（JSON形式の mcpServers） … こちら

A. Hermes Agent に接続する

Hermes Agent は YAML の設定ファイル（config.yaml）を使います。認証あり／なしで手順が少し変わります。

⚠️ 重要な注意（実体験に基づく落とし穴） Hermes Agent の MCP 設定では、env: ブロックは子プロセスに渡されません（Claude Desktop とは挙動が異なります）。 そのため、認証トークンは ~/.hermes/.env ファイルに保存し、config.yaml 側では ${変数名} で参照します。 config.yaml 内に ${変数名} と書くと、Hermes が .env の値を展開してヘッダーに渡します。

A-1. 認証なし（MCP_AUTH_TOKEN を設定していない場合）

config.yaml に次を追記します：

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

A-2. 認証あり（推奨：MCP_AUTH_TOKEN を設定した場合）

Step 1. トークンを ~/.hermes/.env に保存する

.env に保存する値は、Bearer を先頭に付けた合言葉にします（Bearer と合言葉の間は半角スペース1つ）。

# 例：合言葉が bfe60fec...ec78 の場合
echo 'CLICKUP_MAMORU_AUTH=Bearer bfe60fecc14e1d912e1e902cdd53e34434143a42edaf3a9a6a7348f84e26ec78' >> ~/.hermes/.env

• CLICKUP_MAMORU_AUTH は任意の変数名です（分かりやすい名前でOK）。

• 値の合言葉は、Railway の MCP_AUTH_TOKEN と完全に一致させてください。

Step 2. config.yaml で変数を参照する

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

• ${CLICKUP_MAMORU_AUTH} は Step 1 で .env に書いた変数名に合わせます。

• "Authorization:${...}" の Authorization: の直後にスペースは入れません（スペースは .env 値の Bearer 側にあります）。

• ${...} は Hermes が .env から展開します。ここに合言葉を直書きしないでください。

Step 3. セッションを再起動する

設定を反映するため、Hermes で次を実行します：

/reset

A-3. 接続のコツ（まとめ）

💡 認証ヘッダーが空のまま接続すると、tools/list（接続テスト）は通っても、実際のツール実行でタイムアウト/切断します。.env の値と ${変数名} の対応を必ず確認してください。

A-4. （おすすめ）設定を Hermes に丸ごと任せる

上記の手順は、Hermes Agent 自身に代行させることもできます。 次のプロンプトをコピーし、【あなたのRailwayドメイン】 と 【手順1で生成した合言葉】 の2か所だけ自分の値に置き換えて Hermes に渡してください。

🔐 認証あり版（MCP_AUTH_TOKEN を設定済みの場合・推奨）

ClickUp MCP サーバーを、このエージェントに接続できるよう設定してください。
あなた（Hermes Agent）の設定ファイルを直接編集して構いません。

【接続情報】
- MCPサーバーURL: https://【あなたのRailwayドメイン】.up.railway.app/sse
- 認証方式: Bearer トークン
- 合言葉（MCP_AUTH_TOKEN）: 【手順1で生成した合言葉】

【設定手順】
1. ~/.hermes/.env に、次の1行を追記してください（既存内容は消さず追記）。
   値は "Bearer " + 合言葉 です（Bearer と合言葉の間は半角スペース1つ）。
     CLICKUP_MAMORU_AUTH=Bearer 【手順1で生成した合言葉】

2. config.yaml の mcp_servers に、次のエントリを追加してください。
     mcp_servers:
       clickup-mamoru:
         command: npx
         args:
           - -y
           - mcp-remote
           - https://【あなたのRailwayドメイン】.up.railway.app/sse
           - --header
           - "Authorization:${CLICKUP_MAMORU_AUTH}"
         timeout: 60

【重要な注意】
- env: ブロックは使わないでください（Hermes は env: を子プロセスに渡しません）。
  必ず ~/.hermes/.env にトークンを保存し、config.yaml では ${CLICKUP_MAMORU_AUTH} で参照してください。
- "Authorization:${...}" の Authorization: の直後にスペースを入れないでください
  （"Bearer " のスペースは .env の値の側に含まれています）。

3. 設定が終わったら /reset でセッションを再起動してください。

完了後、get_workspaces ツールを実行して、私の ClickUp ワークスペース一覧を表示してください。
接続が成功しているか確認したいです。

🔓 認証なし版（MCP_AUTH_TOKEN を設定していない場合）

ClickUp MCP サーバーを、このエージェントに接続できるよう設定してください。
あなた（Hermes Agent）の設定ファイルを直接編集して構いません。

【接続情報】
- MCPサーバーURL: https://【あなたのRailwayドメイン】.up.railway.app/sse
- 認証: なし

【設定手順】
1. config.yaml の mcp_servers に、次のエントリを追加してください。
     mcp_servers:
       clickup-mamoru:
         command: npx
         args:
           - -y
           - mcp-remote
           - https://【あなたのRailwayドメイン】.up.railway.app/sse
         timeout: 60

2. 設定が終わったら /reset でセッションを再起動してください。

完了後、get_workspaces ツールを実行して、私の ClickUp ワークスペース一覧を表示してください。

Hermes が /reset を自動実行できない場合は、最後に自分で /reset を打てばOKです。

B. Claude Desktop など（JSON形式）

JSON形式で mcpServers を設定するクライアント（Claude Desktop 等）では、次のように記述します（認証なしの例）：

{
  "mcpServers": {
    "clickup": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://【あなたのRailwayドメイン】.up.railway.app/sse"
      ]
    }
  }
}

認証ありの場合のヘッダーの付け方は、後述の 🔐（任意）アクセス認証を有効にする を参照してください。

共通

• 【あなたのRailwayドメイン】 を、ステップ4で発行した自分のURLに置き換えます。

• URL の末尾に必ず /sse を付けてください。

• 設定後はクライアントを再起動（Hermesは /reset）すると、ClickUp ツール（get_tasks, create_task など）が使えます。

試しに「私のClickUpのワークスペース一覧を見せて」と聞いてみてください。get_workspaces ツールが動けば接続成功です。

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

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

仕組みはシンプルです：

サーバーに合言葉(MCP_AUTH_TOKEN)を設定
   → 接続時に Authorization: Bearer <合言葉> が一致しないと 401 で拒否
   → クライアント(mcp-remote)が同じ合言葉をヘッダーで送る

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文字の合言葉を生成できます。

生成された文字列（例：a1b2c3... の長い英数字）をコピーしておきます。

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

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

2. New Variable で

   • Name: MCP_AUTH_TOKEN

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

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

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

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

手順 3：クライアント設定にヘッダーを追加する

クライアントによって書き方が異なります。

Hermes Agent の場合

~/.hermes/.env にトークンを保存し、config.yaml から ${変数名} で参照します。 詳細手順は ステップ5-A-2「認証あり」 を参照してください。要点：

# ~/.hermes/.env （値は "Bearer " + 合言葉）
echo 'CLICKUP_MAMORU_AUTH=Bearer 【手順1の合言葉】' >> ~/.hermes/.env

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

変更後は /reset で再起動。Hermes では env: ブロックは効きません。

Claude Desktop など（JSON形式）の場合

JSON の env ブロックで変数を渡せます：

{
  "mcpServers": {
    "clickup": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://【あなたのRailwayドメイン】.up.railway.app/sse",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer 【手順1で生成した合言葉】"
      }
    }
  }
}

• env の AUTH_HEADER には Bearer を先頭に付けた合言葉を入れます（Bearer と合言葉の間は半角スペース1つ）。

• --header の値で ${AUTH_HEADER} と書くのは、値にスペースが含まれても正しく処理されるようにするための書き方です。そのままコピーしてください。

設定後、クライアントを再起動すれば、合言葉付きで接続できます。

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

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

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

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

# 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 を利用しています。