# ClickUp MCP Server

A [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server that provides comprehensive access to the [ClickUp API](https://clickup.com/api) — enabling AI assistants like Cline, Claude Code, and others to read, write, update, and delete ClickUp documentation, plus access the full ClickUp API surface.

## ✨ Features

### 📄 Docs Management (v3 API)
Full CRUD operations on ClickUp Docs and Pages:
- `get_docs` / `get_doc` / `get_doc_pages` / `get_doc_page` — Read docs & pages
- `create_doc` / `create_doc_page` — Create docs & pages
- `update_doc` / `update_doc_page` — Update docs & pages
- `delete_doc` / `delete_doc_page` — Delete docs & pages
- `get_doc_blocks` / `create_doc_blocks` / `update_doc_blocks` / `delete_doc_blocks` — Block-level editing

### 🗂️ Full ClickUp API Coverage (84+ tools)
- **Workspaces**: Get teams & workspace details
- **Spaces**: Full CRUD for spaces
- **Folders**: Full CRUD for folders
- **Lists**: Full CRUD for lists
- **Tasks**: Full CRUD, filtering, status updates, assignees, tags
- **Comments**: Read/create/update/delete on tasks & lists
- **Checklists**: Full CRUD for checklists & items
- **Members**: View & invite team members
- **Goals**: Full CRUD for goals
- **Time Tracking**: View/create/delete time entries
- **Views**: Read views at any level
- **Webhooks**: Full CRUD for webhooks
- **Tags**: Full CRUD for space tags
- **Custom Fields**: Read & set custom field values
- **Task Templates**: Read/create/delete templates
- **Plus**: Task relationships, links, dependencies, attachments, guests, roles, shared hierarchy

## 📦 Installation

### ⚡ Cara Tercepat: Install Langsung via Cline (Paste Link GitHub)

Setelah repo ini di-push ke GitHub, kamu bisa langsung install MCP server ini ke Cline dengan cara:

1. **Copy link GitHub repo** ini, contoh:
   ```
   https://github.com/azukhrufy/clickup-mcp-server
   ```

2. **Paste link tersebut ke Cline** dan beri perintah seperti ini:
   ```
   Install MCP server dari repo ini: https://github.com/azukhrufy/clickup-mcp-server
   ```
   atau
   ```
   Tambahkan MCP server ClickUp dari https://github.com/azukhrufy/clickup-mcp-server
   ```

3. **Cline akan otomatis:**
   - Clone repo ke folder MCP servers
   - Install dependencies (`npm install`)
   - Build project (`npm run build`)
   - Menambahkan konfigurasi ke `cline_mcp_settings.json`

4. **Masukkan ClickUp API Token** saat diminta (lihat bagian [Konfigurasi](#-konfigurasi))

5. **Restart Cline** — tools ClickUp akan muncul di panel MCP servers

### 📦 Install Langsung dari GitHub (Tanpa Path Lokal)

Cara ini langsung mengarah ke link GitHub — **tidak perlu path lokal**. `npx` akan otomatis clone, install, build, dan jalankan dari repo GitHub.

Konfigurasi di `cline_mcp_settings.json`:
```json
{
  "mcpServers": {
    "clickup": {
      "command": "npx",
      "args": ["-y", "github:azukhrufy/clickup-mcp-server"],
      "env": {
        "CLICKUP_API_TOKEN": "pk_your_api_token_here"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}
```

**Untuk branch tertentu:**
```json
{
  "args": ["-y", "github:azukhrufy/clickup-mcp-server#branch-name"]
}
```

### 📦 Install via npx (Setelah di-publish ke npm)

```bash
# Langsung jalankan tanpa clone
npx clickup-mcp-server
```

Konfigurasi di `cline_mcp_settings.json`:
```json
{
  "mcpServers": {
    "clickup": {
      "command": "npx",
      "args": ["-y", "clickup-mcp-server"],
      "env": {
        "CLICKUP_API_TOKEN": "pk_your_api_token_here"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}
```

### 📦 Install Manual (Clone)

```bash
# Clone the repository
git clone https://github.com/azukhrufy/clickup-mcp-server.git
cd clickup-mcp-server

# Install dependencies
npm install

# Build the server
npm run build
```

## 🔑 Configuration

### 1. Get a ClickUp API Token
1. Log in to [ClickUp](https://app.clickup.com)
2. Go to **Settings → Apps** (or [https://app.clickup.com/settings/apps](https://app.clickup.com/settings/apps))
3. Click **Generate** under the API Token section
4. Copy the token (starts with `pk_` for Personal Tokens)

### 2. Add to Cline (VS Code)
Add the MCP server to your Cline settings file:
`~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`

```json
{
  "mcpServers": {
    "clickup": {
      "command": "node",
      "args": ["/absolute/path/to/clickup-mcp-server/build/index.js"],
      "env": {
        "CLICKUP_API_TOKEN": "pk_your_api_token_here"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}
```

### 3. Add to Claude Desktop
Edit `claude_desktop_config.json`:
```json
{
  "mcpServers": {
    "clickup": {
      "command": "node",
      "args": ["/absolute/path/to/clickup-mcp-server/build/index.js"],
      "env": {
        "CLICKUP_API_TOKEN": "pk_your_api_token_here"
      }
    }
  }
}
```

## 🚀 Usage

### Reading a ClickUp Doc
ClickUp doc URLs follow this format:
```
https://app.clickup.com/{team_id}/v/dc/{doc_id}/{page_id}
```

Example with the Cline tools:
```
get_doc_page(team_id="36768531", doc_id="1322rk-9596", page_id="1322rk-32376")
```

### Example prompts you can ask your AI assistant:
- "List my ClickUp workspaces"
- "Get all docs in my workspace"  
- "Read the contents of doc XYZ page 123"
- "Create a new doc called 'Meeting Notes'"
- "Update the status of task ABC to 'in progress'"
- "Create a checklist on task DEF"

## 🛠️ Development

```bash
# Watch mode for development
npm run dev

# Build TypeScript
npm run build
```

## 📁 Project Structure

```
clickup-mcp-server/
├── src/
│   ├── index.ts          # MCP server implementation (tool definitions & handlers)
│   └── clickup-api.ts    # ClickUp API v2 + v3 client wrapper
├── build/                # Compiled JavaScript output
├── tsconfig.json
├── package.json
└── README.md
```

## 🔧 Architecture Notes

- **Dual API clients**: The server uses ClickUp's **v2 API** for standard endpoints (teams, spaces, tasks, etc.) and **v3 API** for Docs endpoints (`/workspaces/{team_id}/docs/...`)
- **Stdio transport**: Communication happens over standard input/output
- **TypeScript**: Full type safety with strict mode
- **Error handling**: Standardized error messages with HTTP status codes

## 📄 License

MIT

## 🤝 Contributing

Contributions are welcome! Feel free to open issues or submit pull requests.