# 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分**。プログラミングの知識は不要です。

---

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

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

1. [ClickUp](https://app.clickup.com/) にログインします。
2. 画面**右上のアバター（自分のアイコン）**をクリック。
3. **Settings（設定）** を開きます。
4. 左メニューの一番下あたりにある **Apps** をクリック。
5. **API Token** の項目で **Generate（生成）** ボタンを押します。
6. `pk_` で始まる文字列が表示されます。これがあなたのトークンです。
   **「Copy」を押してコピーし、メモ帳などに一時保存**しておいてください。

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

---

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

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

1. [GitHub](https://github.com/) のアカウントを持っていない場合は、まず無料登録します。
2. このリポジトリのページを開きます。
3. 画面**右上の「Fork」ボタン**をクリック。
4. 「Create fork」を押すと、`あなたのユーザー名/clickup-mcp-dist` という名前で自分のコピーが作成されます。

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

---

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

[Railway](https://railway.app/) は、コードを自動でサーバーとして公開してくれるサービスです。無料枠から始められます。

1. [Railway](https://railway.app/) にアクセスし、**「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 サーバーを追加して」** と指示してください。

```yaml
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](https://nodejs.org/)（v20以上）** が必要です（`npx` を使うため）。
> 設定後、Hermes で `/reset` を実行すると反映されます。「私のClickUpのワークスペース一覧を見せて」と頼み、`get_workspaces` が動けば接続成功です。

---

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

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

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

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

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

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

```bash
# Mac / Linux
openssl rand -hex 32
```

```powershell
# 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](#ステップ-5hermes-agent-に-mcp-を追加する)の `${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で直接動かすこともできます。

```bash
# 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種）

| カテゴリ | ツール |
|---|---|
| **タスク（基本）** | `get_tasks`, `create_task`, `get_task`, `update_task`, `delete_task` |
| **タスク（一括）** | `create_bulk_tasks`, `update_bulk_tasks` |
| **タスク（関連付け）** | `add_task_link`, `remove_task_link`, `add_dependency`, `remove_dependency`, `move_task_to_list`, `add_task_to_list` |
| **コメント** | `add_task_comment`, `get_task_comments`, `get_threaded_replies` |
| **タグ** | `add_tag_to_task`, `remove_tag_from_task`, `search_tasks_by_tag` |
| **カスタムフィールド** | `set_custom_field` |
| **ワークスペース** | `get_workspaces`, `get_workspace_hierarchy`, `get_workspace_members`, `find_member_by_name` |
| **スペース** | `get_spaces`, `create_space` |
| **フォルダ** | `get_folders`, `create_folder`, `update_folder` |
| **リスト** | `get_lists`, `create_list`, `get_folderless_lists`, `create_folderless_list`, `get_list`, `update_list` |
| **検索** | `search_workspace`, `search_tasks_by_tag` |
| **時間計測** | `get_task_time_entries`, `get_current_time_entry`, `start_time_tracking`, `stop_time_tracking`, `add_time_entry`, `get_time_entries_for_tasks` |
| **レポート** | `get_time_in_status_for_task`, `get_time_in_status_for_list` |
| **チャット** | `get_chat_channels`, `send_chat_message` |
| **Docs** | `create_document`, `list_document_pages`, `get_document_pages`, `create_document_page`, `update_document_page` |

---

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

| 症状 | 原因と対処 |
|---|---|
| Railwayのログに `CLICKUP_API_TOKEN が設定されていません` | ステップ4の環境変数が未設定。Variables タブを確認 |
| AIが接続できない | URL末尾の `/sse` が抜けている／ドメインが未発行。ステップ4を確認 |
| Generate Domain でポートを聞かれる | `8080` を入力してください（Railwayの標準ポート） |
| ドメインにアクセスしても応答が無い（502等） | Generate Domain のポートが `8080` 以外になっている。`8080` で再設定 |
| `npx` でエラー | PCに Node.js (v20以上) が未インストール。[nodejs.org](https://nodejs.org/) から導入 |
| ツールが `Oauth token not found` 等を返す | トークンが間違っている／失効。ステップ1で再生成し、Railwayの値を更新 |
| `401 Unauthorized`／接続テストは通るが**実行でタイムアウト/切断** | 認証ON時、合言葉の不一致 or 未設定。`${CLICKUP_MAMORU_AUTH}` を `Bearer <合言葉>` に置き換え、Railwayの `MCP_AUTH_TOKEN` と完全一致させる |
| 設定を変えても反映されない | Hermes で `/reset` を実行してセッションを再起動する |
| デプロイが失敗する | Railwayの「Deployments」ログを確認。`npm run build` のエラー内容を参照 |

---

## ライセンス

[MIT License](./LICENSE) — 自由に利用・改変・再配布できます。

---

## 謝辞

[Model Context Protocol](https://modelcontextprotocol.io/) および [ClickUp API](https://clickup.com/api) を利用しています。