Mcp Click Up

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 [--notes] | clickup_get_task | | Mark task complete | cupt | cupt done [--dry-run] | clickup_update_task | | Add note/comment | cupt | cupt note "" | clickup_manage_comments | | Read comments | cupt | cupt notes | clickup_manage_comments | | Start/stop timer | cupt | cupt time start / cupt time stop | MCP time tracking | | Log time manually | cupt | cupt time add | MCP time tracking | | Add tag | cupt | cupt tag add | clickup_add_tag_to_task | | Remove tag | cupt | cupt tag remove | clickup_remove_tag_from_task | | Task context | cupt | cupt context | n/a | | Discover statuses | cupt | cupt statuses | 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

# 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 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

cupt --version   # e.g. cupt 0.7.1
cupt status      # Shows workspace + auth status

Step 2: Install if missing

bash .opencode/skills/mcp-click-up/scripts/install.sh

Step 3: Authenticate

cupt auth                          # Interactive wizard
# OR:
cupt config --api-token pk_xxxxx   # Direct token setup

Step 4: Set defaults (optional)

cupt config --workspace-id     # From cupt status
cupt config --default-list     # For quick task creation

Step 5: Use for daily operations

cupt list --today --json           # Tasks due today, JSON output
cupt statuses             # Discover list's status schema FIRST
cupt done  --dry-run      # Preview completion without writing
cupt done  --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):

"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:

// 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 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 --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 --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 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 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 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 returns status list for the task's list
• [ ] Dry-run before batch: cupt done --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__codemode_calltoolchain 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 | Set default workspace | | | cupt config --default-list | 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 | Filter by tag (server-side, fast) | | | cupt list --team | 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 | Full task details | | | cupt show --notes | Include comments | | | cupt show --json | JSON output | | | cupt show --offline | Use cached data | | | cupt context | Parent + siblings + subtasks | | | cupt statuses | Status schema for task's list | | | cupt done | Mark complete (auto-resolves status) | | | cupt done --dry-run | Preview completion, no write | | | cupt done --note "text" | Mark complete with note | | Notes | cupt note "" | Add comment to task | | | cupt notes | List all comments | | Time | cupt time start | Start timer on task | | | cupt time stop | Stop running timer | | | cupt time add | Log time (e.g., 1h30m, 45m) | | | cupt time status | Show current timer state | | Tags | cupt tag add | Add tag to task | | | cupt tag remove | Remove tag from task | | Attach | cupt attach list | List attachments | | | cupt attach add | Upload file | | | cupt attach get | 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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: MichelKerkmeester
• Source: MichelKerkmeester/opencode--skilled-agent-loops-with-spec-kit-memory
• License: MIT

Install and usage instructions live in the source repository linked above.