mcp-click-up

<!-- keywords: clickup cupt task-management work-queue time-tracking mcp -->

# mcp-click-up Skill

ClickUp task management via **cupt CLI** (primary) and **official ClickUp MCP** (secondary). Operation-based routing: cupt handles daily task ops, MCP handles documents, goals, and bulk operations.

---

## 1. WHEN TO USE

### Activation Triggers (explicit user phrases)

- "clickup", "cupt", "mcp-click-up", "click up"
- "manage tasks", "list tasks", "mark task done", "complete task"
- "log time", "track time", "start timer", "stop timer"
- "add note to task", "tag task", "show task details"
- "process work queue", "process task queue"
- "clickup documents", "clickup goals", "bulk create tasks"

### Automatic Triggers (keyword patterns)

- `cupt` appears in the request
- `clickup` + any action verb (list, show, done, mark, note, time, tag)
- "work queue" or "task queue" in a ClickUp context
- "time tracking" or "work log" with project management context
- MCP tool names: `clickup_create_task`, `clickup_get_task`, `clickup_manage_documents`

### When NOT to Use

- **@krodak/clickup-cli (`cu` command)** — different tool entirely; not supported by this skill
- Community ClickUp MCP servers (@taazkareem/clickup-mcp-server) — use official MCP only
- Direct ClickUp REST API calls (no CLI/MCP) — this skill adds no value there
- Browser-based ClickUp automation (Playwright/Puppeteer) — wrong surface

---

## 2. SMART ROUTING

### Resource Loading Levels

```
ALWAYS:    SKILL.md (this file)
ON_DEMAND: references/cupt_commands.md    (when cupt command details needed)
           references/mcp_tools.md         (when MCP tool details needed)
           references/troubleshooting.md   (when error or auth issue detected)
```

### Operation-to-Tool Routing Table

| Operation | Primary Tool | Command | MCP Fallback |
|-----------|-------------|---------|-------------|
| List/filter tasks | cupt | `cupt list [--today\|--week\|--tag X]` | `clickup_search_tasks` |
| Task details | cupt | `cupt show <id> [--notes]` | `clickup_get_task` |
| Mark task complete | cupt | `cupt done <id> [--dry-run]` | `clickup_update_task` |
| Add note/comment | cupt | `cupt note <id> "<text>"` | `clickup_manage_comments` |
| Read comments | cupt | `cupt notes <id>` | `clickup_manage_comments` |
| Start/stop timer | cupt | `cupt time start <id>` / `cupt time stop` | MCP time tracking |
| Log time manually | cupt | `cupt time add <id> <dur>` | MCP time tracking |
| Add tag | cupt | `cupt tag add <id> <name>` | `clickup_add_tag_to_task` |
| Remove tag | cupt | `cupt tag remove <id> <name>` | `clickup_remove_tag_from_task` |
| Task context | cupt | `cupt context <id>` | n/a |
| Discover statuses | cupt | `cupt statuses <id>` | n/a |
| **Documents** | **MCP only** | n/a | `clickup_create_document` |
| **Goals/OKRs** | **MCP only** | n/a | goal management tools |
| **Bulk create 5+** | **MCP only** | n/a | `clickup_create_bulk_tasks` |
| **Webhooks** | **MCP only** | n/a | webhook management tools |
| **Chat** | **MCP only** | n/a | chat tools |
| **Audit logs** | **MCP only** | n/a | `clickup_get_audit_logs` |

### Smart Router Pseudocode

```python
# Intent signals with weights
INTENT_SIGNALS = {
    "CUPT_DAILY": {
        "weight": 5,
        "keywords": ["list", "show", "done", "note", "notes", "time", "tag", "context",
                     "statuses", "summary", "teams", "attach", "work queue", "complete task",
                     "mark done", "log time", "track time"],
    },
    "MCP_ADVANCED": {
        "weight": 5,
        "keywords": ["document", "goal", "okr", "bulk", "webhook", "chat", "audit",
                     "create_bulk", "manage_documents", "checklist", "custom field"],
    },
    "INSTALL": {
        "weight": 6,
        "keywords": ["install cupt", "setup", "not found", "not installed", "auth",
                     "authenticate", "api token", "mcp config"],
    },
    "TROUBLESHOOT": {
        "weight": 6,
        "keywords": ["error", "failed", "not working", "403", "401", "slow", "timeout",
                     "empty", "no tasks"],
    },
}

RESOURCE_MAP = {
    "CUPT_DAILY":    ["references/cupt_commands.md"],
    "MCP_ADVANCED":  ["references/mcp_tools.md"],
    "INSTALL":       ["INSTALL_GUIDE.md", "scripts/install.sh"],
    "TROUBLESHOOT":  ["references/troubleshooting.md"],
    "DEFAULT":       ["references/cupt_commands.md"],
}

def route_clickup_resources(request: str) -> list[str]:
    """Score intents, load matching reference files."""
    request_lower = request.lower()

    scores = {}
    for intent, config in INTENT_SIGNALS.items():
        score = sum(
            config["weight"] for kw in config["keywords"]
            if kw in request_lower
        )
        if score > 0:
            scores[intent] = score

    if not scores:
        return load_resources(RESOURCE_MAP["DEFAULT"])

    # Error/install keywords boost TROUBLESHOOT/INSTALL regardless of other signals
    if scores.get("TROUBLESHOOT", 0) > 3:
        return load_resources(RESOURCE_MAP["TROUBLESHOOT"])
    if scores.get("INSTALL", 0) > 4:
        return load_resources(RESOURCE_MAP["INSTALL"])

    # Pick top intent
    top_intent = max(scores, key=scores.get)
    return load_resources(RESOURCE_MAP[top_intent])

def load_resources(resource_list: list[str]) -> list[str]:
    """Load resource files, guard to skill directory."""
    skill_root = ".opencode/skills/mcp-click-up/"
    loaded = []
    for resource in resource_list:
        path = skill_root + resource
        if _guard_in_skill(path):
            loaded.append(Read(path))
    return loaded
```

---

## 3. HOW IT WORKS

### Tool Comparison

| Dimension | cupt CLI | Official ClickUp MCP |
|-----------|---------|---------------------|
| **Activation** | `cupt <command>` in Bash | Code Mode `call_tool_chain()` |
| **Best for** | Daily task ops, time tracking, notes, tags | Documents, goals, bulk ops, webhooks |
| **Output** | Human-readable + `--json` flag | Structured JSON always |
| **Auth** | `cupt auth` / `cupt config --api-token` | `CLICKUP_API_KEY` env var |
| **Offline** | `--offline` flag uses local cache | Always requires network |
| **Install** | `pipx install cupt` (Python) | `npx @clickup/mcp-server` (Node) |
| **Dry-run** | `cupt done --dry-run` | No equivalent |
| **Status auto** | Yes — resolves per-list | No — must specify status |

### cupt CLI (Primary Path)

**Step 1: Verify installation**
```bash
cupt --version   # e.g. cupt 0.7.1
cupt status      # Shows workspace + auth status
```

**Step 2: Install if missing**
```bash
bash .opencode/skills/mcp-click-up/scripts/install.sh
```

**Step 3: Authenticate**
```bash
cupt auth                          # Interactive wizard
# OR:
cupt config --api-token pk_xxxxx   # Direct token setup
```

**Step 4: Set defaults (optional)**
```bash
cupt config --workspace-id <id>    # From cupt status
cupt config --default-list <id>    # For quick task creation
```

**Step 5: Use for daily operations**
```bash
cupt list --today --json           # Tasks due today, JSON output
cupt statuses <task_id>            # Discover list's status schema FIRST
cupt done <task_id> --dry-run      # Preview completion without writing
cupt done <task_id> --note "done"  # Mark complete with note
```

### Official ClickUp MCP (Secondary Path)

**Prerequisites:**
- Code Mode MCP configured in opencode.json (see INSTALL_GUIDE.md)
- `CLICKUP_API_KEY` and `CLICKUP_TEAM_ID` set in env block

**Configuration** (add to `opencode.json` mcpServers):
```json
"clickup": {
  "command": "npx",
  "args": ["-y", "@clickup/mcp-server"],
  "env": {
    "CLICKUP_API_KEY": "pk_YOUR_TOKEN",
    "CLICKUP_TEAM_ID": "YOUR_WORKSPACE_ID"
  }
}
```

**Invocation via Code Mode:**
```typescript
// Tool naming: clickup.clickup_{tool_name}
const result = await call_tool_chain([
  {
    tool: "clickup.clickup_create_document",
    input: {
      name: "Sprint Notes",
      parent: { type: 4, id: "LIST_ID" },
      content: "# Sprint Notes\n\n..."
    }
  }
]);
```

**When to prefer MCP:**
- Creating or reading ClickUp Documents
- Managing Goals and OKRs
- Bulk-creating 5+ tasks simultaneously
- Webhooks, custom views, user groups
- Enterprise features (audit logs, guests)

**Limitations:**
- No dry-run for task completion (always specify correct status)
- No offline mode
- Requires Code Mode MCP to be configured

---

## 4. RULES

### ALWAYS

1. **Run `cupt statuses <id>` before any `cupt done` call** — each ClickUp list has its own status schema; the closed status varies (Done, Complete, Closed, etc.). Never assume.
2. **Use `cupt done <id> --dry-run` before batch completion** — verify resolved status for every task before writing. One dry-run per task in a batch loop.
3. **Use `--json` flag for all cupt read commands** when processing output programmatically: `cupt list --json`, `cupt show <id> --json`, etc.
4. **Run `cupt --version && cupt status` as preflight** before starting a ClickUp workflow session.
5. **Treat empty `cupt list` results as valid** — an empty queue is not an error. Before escalating: check tag spelling, try `--all` flag, verify team name via `cupt teams`.
6. **Use `cupt context <id>`** before acting on a task to understand its parent and sibling relationships.

### NEVER

1. **Never hardcode status names across tasks** — `"Done"` in one list may not exist in another. Use `cupt statuses <id>` to discover the correct status for each task's list.
2. **Never run `cupt done` on multiple tasks without per-task dry-run first** — batch status errors are hard to reverse.
3. **Never use `@krodak/clickup-cli` (`cu` command)** — this is a different tool not supported by this skill. The `cu` binary also conflicts with the system `cu` command on some Unix systems.
4. **Never auto-modify `opencode.json`** — print MCP config snippets for user to apply; never write to config files programmatically.
5. **Never fabricate tasks** — if `cupt list` returns empty, the queue is genuinely empty. Report this clearly.
6. **Never use the MCP for daily task ops** — cupt handles these more efficiently and with dry-run safety.

### ESCALATE IF

- cupt is not installed and `scripts/install.sh` fails → report Python version and pip issues
- `cupt status` shows auth failure → direct to `cupt auth` or `cupt config --api-token`
- `cupt list --team X` is extremely slow (>30s) → team filter is client-side on large workspaces; suggest combining with `--tag` to reduce result set
- MCP connection fails → verify `CLICKUP_API_KEY` env var and `CLICKUP_TEAM_ID` in opencode.json
- Task status after `cupt done` is unexpected → run `cupt statuses <id>` and report available statuses

---

## 5. SUCCESS CRITERIA

- [ ] `cupt --version` prints version string
- [ ] `cupt status` shows workspace name without error
- [ ] `cupt list --today --json` returns valid JSON array (even if empty)
- [ ] `cupt statuses <id>` returns status list for the task's list
- [ ] Dry-run before batch: `cupt done <id> --dry-run` shows resolved status
- [ ] For MCP operations: Code Mode `clickup.clickup_get_workspace` returns workspace data

---

## 6. INTEGRATION POINTS

**Gate 2 (Skill Routing):** This skill activates at ≥0.8 confidence for ClickUp task management requests. The skill advisor matches on: `clickup`, `cupt`, `task management`, `work queue`, `time tracking`, `mark done`.

**Code Mode MCP:** Official ClickUp MCP tools are invoked via `mcp__code_mode__call_tool_chain`. Tool naming convention: `clickup.clickup_{tool_name}`. See references/mcp_tools.md for the full tool catalog.

**Memory:** Save ClickUp workflow context (current list, active tags, workspace ID) using `/memory:save` when switching sessions.

**Tool Usage:** Use Bash for cupt CLI commands. Use mcp__code_mode__call_tool_chain for official MCP operations. Use Read to load references on demand.

---

## 7. QUICK REFERENCE

### cupt Command Cheat Sheet

| Category | Command | Description |
|----------|---------|-------------|
| **Auth** | `cupt auth` | Interactive authentication wizard |
| | `cupt config --api-token pk_xxx` | Set Personal API Token directly |
| | `cupt status` | Show auth status + workspace |
| | `cupt logout` | Clear stored credentials |
| **Config** | `cupt config --workspace-id <id>` | Set default workspace |
| | `cupt config --default-list <id>` | Set default list |
| | `cupt config --show` | Display current configuration |
| **Tasks** | `cupt list` | List assigned tasks |
| | `cupt list --today` | Tasks due today |
| | `cupt list --week` | Tasks due this week |
| | `cupt list --overdue` | Overdue tasks |
| | `cupt list --tag <name>` | Filter by tag (server-side, fast) |
| | `cupt list --team <name>` | Filter by team (client-side, slow) |
| | `cupt list --all` | All tasks including team |
| | `cupt list --mine` | Only self-assigned tasks |
| | `cupt list --json` | JSON output for agents |
| | `cupt show <id>` | Full task details |
| | `cupt show <id> --notes` | Include comments |
| | `cupt show <id> --json` | JSON output |
| | `cupt show <id> --offline` | Use cached data |
| | `cupt context <id>` | Parent + siblings + subtasks |
| | `cupt statuses <id>` | Status schema for task's list |
| | `cupt done <id>` | Mark complete (auto-resolves status) |
| | `cupt done <id> --dry-run` | Preview completion, no write |
| | `cupt done <id> --note "text"` | Mark complete with note |
| **Notes** | `cupt note <id> "<text>"` | Add comment to task |
| | `cupt notes <id>` | List all comments |
| **Time** | `cupt time start <id>` | Start timer on task |
| | `cupt time stop` | Stop running timer |
| | `cupt time add <id> <dur>` | Log time (e.g., `1h30m`, `45m`) |
| | `cupt time status` | Show current timer state |
| **Tags** | `cupt tag add <id> <name>` | Add tag to task |
| | `cupt tag remove <id> <name>` | Remove tag from task |
| **Attach** | `cupt attach list <id>` | List attachments |
| | `cupt attach add <id> <file>` | Upload file |
| | `cupt attach get <id> <sel>` | Download attachment |
| **Workspace** | `cupt teams` | List teams (user-groups) |
| | `cupt summary` | Task summary overview |
| | `cupt prefetch` | Pre-cache tasks for offline use |

---

## 8. REFERENCES AND RELATED RESOURCES

**Reference Files (load on demand via router):**
- `references/cupt_commands.md` — Full cupt command reference with agent patterns
- `references/mcp_tools.md` — 46 official MCP tools, priority table, invocation
- `references/troubleshooting.md` — Auth, status, team-filter, MCP failures

**Scripts:**
- `scripts/install.sh` — Installs cupt + prints MCP config snippet

**Embedded Servers:**
- `mcp-servers/clickup-mcp/package.json` — Official ClickUp MCP server (`@clickup/mcp-server`). Run `npm install` to vendor locally.
- `mcp-servers/clickup-cli/requirements.txt` — cupt CLI pip pin (`cupt>=0.7.1`). Run `setup.sh` to install.
- `mcp-servers/clickup-cli/setup.sh` — cupt install via pipx or pip.

**Install Guide:**
- `INSTALL_GUIDE.md` — Step-by-step with validation checkpoints

**Examples:**
- `examples/task-queue-workflow.sh` — Process tagged work queue
- `examples/time-tracking-workflow.sh` — Timer + time log workflow

**Related Skills:**
- `mcp-chrome-devtools` — Structural template this skill was modeled on
- `mcp-code-mode` — Code Mode MCP orchestration (used for official MCP invocation)

**External:**
- cupt repository: https://github.com/newz2000/cupt
- Official ClickUp MCP: https://github.com/clickup/clickup-mcp-server
- ClickUp API tokens: https://app.clickup.com/settings/apps