clickup-mcp

# ClickUp MCP (Official)

Access ClickUp via the official MCP server. Full workspace search, task management, time tracking, comments, chat, and docs.

## Setup

### Option 1: Direct OAuth (Supported Clients Only)

ClickUp MCP only allows OAuth from **allowlisted clients**:
- Claude Desktop, Claude Code, Cursor, VS Code, Windsurf, ChatGPT

```bash
# Claude Code
claude mcp add clickup --transport http https://mcp.clickup.com/mcp
# Then /mcp in session to authorize
```

### Option 2: Claude Code → mcporter (Recommended)

Use Claude Code to OAuth, then extract token for mcporter:

**Step 1: Authorize via Claude Code**
```bash
claude mcp add clickup --transport http https://mcp.clickup.com/mcp
claude
# In Claude Code, run: /mcp
# Complete OAuth in browser
```

**Step 2: Extract token**
```bash
jq -r '.mcpOAuth | to_entries | .[] | select(.key | startswith("clickup")) | .value.accessToken' ~/.claude/.credentials.json
```

**Step 3: Add to environment**
```bash
# Add to ~/.clawdbot/.env
CLICKUP_TOKEN=eyJhbGciOiJkaXIi...
```

**Step 4: Configure mcporter**

Add to `config/mcporter.json`:
```json
{
  "mcpServers": {
    "clickup": {
      "baseUrl": "https://mcp.clickup.com/mcp",
      "description": "Official ClickUp MCP",
      "headers": {
        "Authorization": "Bearer ${CLICKUP_TOKEN}"
      }
    }
  }
}
```

**Step 5: Test**
```bash
mcporter list clickup
mcporter call 'clickup.clickup_search(keywords: "test", count: 3)'
```

### Token Refresh

Tokens are long-lived (~10 years). If expired:
1. Re-run `/mcp` in Claude Code
2. Re-extract token from `~/.claude/.credentials.json`
3. Update `CLICKUP_TOKEN` in `.env`

## Available Tools (32)

### Search

| Tool | Description |
|------|-------------|
| `clickup_search` | Universal search across tasks, docs, dashboards, chat, files |

### Tasks

| Tool | Description |
|------|-------------|
| `clickup_create_task` | Create task with name, description, status, assignees, due date, priority |
| `clickup_get_task` | Get task details (with optional subtasks) |
| `clickup_update_task` | Update any task field |
| `clickup_attach_task_file` | Attach file to task (URL or base64) |
| `clickup_add_tag_to_task` | Add tag to task |
| `clickup_remove_tag_from_task` | Remove tag from task |

### Comments

| Tool | Description |
|------|-------------|
| `clickup_get_task_comments` | Get all comments on task |
| `clickup_create_task_comment` | Add comment (supports @mentions) |

### Time Tracking

| Tool | Description |
|------|-------------|
| `clickup_start_time_tracking` | Start timer on task |
| `clickup_stop_time_tracking` | Stop active timer |
| `clickup_add_time_entry` | Log time manually |
| `clickup_get_task_time_entries` | Get time entries for task |
| `clickup_get_current_time_entry` | Check active timer |

### Workspace & Hierarchy

| Tool | Description |
|------|-------------|
| `clickup_get_workspace_hierarchy` | Get full structure (Spaces, Folders, Lists) |
| `clickup_create_list` | Create list in Space |
| `clickup_create_list_in_folder` | Create list in Folder |
| `clickup_get_list` | Get list details |
| `clickup_update_list` | Update list settings |
| `clickup_create_folder` | Create folder in Space |
| `clickup_get_folder` | Get folder details |
| `clickup_update_folder` | Update folder settings |

### Members

| Tool | Description |
|------|-------------|
| `clickup_get_workspace_members` | List all workspace members |
| `clickup_find_member_by_name` | Find member by name/email |
| `clickup_resolve_assignees` | Get user IDs from names |

### Chat

| Tool | Description |
|------|-------------|
| `clickup_get_chat_channels` | List all Chat channels |
| `clickup_send_chat_message` | Send message to channel |

### Docs

| Tool | Description |
|------|-------------|
| `clickup_create_document` | Create new Doc |
| `clickup_list_document_pages` | Get Doc structure |
| `clickup_get_document_pages` | Get page content |
| `clickup_create_document_page` | Add page to Doc |
| `clickup_update_document_page` | Edit page content |

## Usage Examples

### Search Workspace

```bash
mcporter call 'clickup.clickup_search(
  keywords: "Q4 marketing",
  count: 10
)'
```

### Create Task

```bash
mcporter call 'clickup.clickup_create_task(
  name: "Review PR #42",
  list_id: "901506994423",
  description: "Check the new feature",
  status: "to do"
)'
```

### Update Task

```bash
mcporter call 'clickup.clickup_update_task(
  task_id: "abc123",
  status: "in progress"
)'
```

### Add Comment

```bash
mcporter call 'clickup.clickup_create_task_comment(
  task_id: "abc123",
  comment_text: "@Mark can you review this?"
)'
```

### Time Tracking

```bash
# Start timer
mcporter call 'clickup.clickup_start_time_tracking(
  task_id: "abc123",
  description: "Working on feature"
)'

# Stop timer
mcporter call 'clickup.clickup_stop_time_tracking()'

# Log time manually (duration in ms, e.g., 2h = 7200000)
mcporter call 'clickup.clickup_add_time_entry(
  task_id: "abc123",
  start: "2026-01-06 10:00",
  duration: "2h",
  description: "Code review"
)'
```

### Get Workspace Structure

```bash
mcporter call 'clickup.clickup_get_workspace_hierarchy(limit: 10)'
```

### Chat

```bash
# List channels
mcporter call 'clickup.clickup_get_chat_channels()'

# Send message
mcporter call 'clickup.clickup_send_chat_message(
  channel_id: "channel-123",
  content: "Team standup in 5 minutes!"
)'
```

## Limitations

- **No delete operations** — Safety measure; use ClickUp UI
- **No custom fields** — Not exposed in official MCP
- **No views management** — Not available
- **OAuth required** — Must use allowlisted client (Claude Code workaround available)
- **Rate limits** — Same as ClickUp API (~100 req/min)

## Resources

- [ClickUp MCP Documentation](https://developer.clickup.com/docs/connect-an-ai-assistant-to-clickups-mcp-server)
- [Supported Tools](https://developer.clickup.com/docs/mcp-tools)
- [ClickUp API Reference](https://clickup.com/api)
- [Feedback / Allowlist Request](https://feedback.clickup.com)