mcp-click-up Skill
ClickUp task management via cupt CLI (primary) and official ClickUp MCP (secondary). Operation-based routing: cupt handles daily task ops, and the MCP handles task creation, documents, search, lists and folders, task relations, chat and reminders. Goals, bulk create, webhooks and checklist edits have no route on either surface.
1. MARKDOWN FORMATTING CONTRACT — READ BEFORE ANY CLICKUP WRITE
ClickUp shows plain text literally. Markdown sent through a plain-text path shows up in the ClickUp UI as raw ### Heading, **bold**, and - [ ] text. Whenever the content contains ANY markdown syntax, use the markdown-aware parameter for the operation. On the Code Mode manual (clickup_official), checked against the server's schema on 2026-10-08:
| Operation | Required parameter |
|---|---|
| Task create or update | markdown_description (the server has no plain description or markdown_content parameter) |
| Document page create, update or read | content_format: "text/md" |
| Task read-back | include: ["description"] on clickup_get_task |
On the raw ClickUp v2 REST API, markdown_content is also accepted on task update and include_markdown_description=true returns markdown, both live-verified 2026-07-15. The claude.ai ClickUp connector was not re-checked on 2026-10-08.
Push shape for a markdown artifact: the document's H1 becomes the task name (drop it from the body); strip internal HTML comments and processing metadata; everything else travels verbatim, with two spellings fixed on the way to a document page. An empty checkbox written - [] imports as literal \[\] text, so send it as - [ ], which imports as a checklist item. A line that opens with a number, a full stop and a bold title, such as 2. **Header**, imports as a one-item numbered list, and because the divider after it ends that list every title reads 1., so send it as 2\. **Header**.
Failure symptom: literal ### or ** visible in a ClickUp task means someone used the plain description field. That is the defect, not a rendering bug.
Write a new doc page browser-first. Create the page through the MCP with the single line [[BODY]], then run the page writer in references/mcp-tools.md section 8, "Browser-first page write". It turns the markdown into editor HTML and pastes it over the placeholder in one change, in the user's logged-in browser. The page lands with tight dividers, real checklists, gray lead numbers on 1\. **Title** and 1 ) **Title** lines, a gray italic Mark-as-done line and [[COLS]] pairs as side-by-side columns. It then checks the saved page after a reload and the markdown read-back. The approved push covers the browser pass, so it needs no second yes.
Fall back to the markdown write and the gap pass. When no browser tool is available, or the user picks it, write the page body as markdown and then check the import and remove the divider gaps. A page the server creates or rewrites shows an empty line under every divider, and no MCP call removes it. Compare the "text/md" read-back with what you sent, count the gaps in the "text/plain" read-back, then remove them in the ClickUp editor with the program in references/mcp-tools.md section 8, "Required after every page write". This path keeps no colour, and it builds columns only through the columns routine in the same section. Never report a page delivered while it has gaps or an import diff.
Side-by-side screenshots go in ClickUp columns, built in the editor. No MCP call writes a columns block. The page writer builds them from [[COLS]] blocks. On the fallback path, write a [[COLS-n]] placeholder line where each pair belongs and run the columns routine in section 8, "Side-by-side columns on a doc page", after the gap pass. A page that holds columns must never be rewritten with replace, because the markdown read-back drops the columns.
Before the first ClickUp MCP write of a session, run the first-use readiness check. A new user has to approve the ClickUp MCP once in the browser, and a doc page push also needs ClickUp logged in, in the browser the gap pass uses. The agent cannot do either. The check in references/mcp-tools.md section 3, "First-Use Readiness Check", finds what is missing, asks the user with the runtime's structured question tool, waits, rechecks and only then writes. MCP task writes need only the MCP part. A cupt write needs neither, because cupt signs in with its own API token.
Worked examples: references/mcp-tools.md (Markdown Transport Contract + invocation patterns).
2. 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 doc page", "create clickup task", "search clickup"
Automatic Triggers (keyword patterns)
cuptappears in the requestclickup+ 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_create_document,clickup_update_document_page
When NOT to Use
- @krodak/clickup-cli (
cucommand) — 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
3. SMART ROUTING
The mcp-tooling hub routes a ClickUp task request here: the request names cupt or clickup with a task action, a work queue, time tracking or a ClickUp document, and the hub's mcp-click-up mode signal selects this packet.
Two surfaces answer it, and the daily operations stay on the cupt CLI while task creation, documents, search, lists and folders, relations, chat and reminders go to the official ClickUp MCP.
references/cupt-commands.md and references/mcp-tools.md are the first leaves the hub ROUTER.md names for this mode.
The markdown formatting contract above this section binds before any ClickUp write.
Read ROUTER.md before selecting skill-local resources; open only the matched files.
4. 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 | Task creation, documents, search, lists and folders, task relations |
| Output | Human-readable + --json flag |
Structured JSON always |
| Auth | cupt auth / cupt config --api-token |
OAuth through the hosted ClickUp server, one browser approval |
| Offline | --offline flag uses local cache |
Always requires network |
| Install | pipx install cupt (Python) |
npx -y mcp-remote https://mcp.clickup.com/mcp (stdio) |
| 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, from the mcp-click-up folder
bash 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 <id> # From cupt status
cupt config --default-list <id> # For quick task creation
Step 5: Use for daily operations
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)
This is ClickUp's official hosted MCP server at https://mcp.clickup.com/mcp.
The registered clickup_official manual reaches it over stdio through npx -y mcp-remote. It authenticates with OAuth, so the first launch needs one approval in the browser. The manual reads no API key.
The npm package @clickup/mcp-server returned 404 on 2026-07-10 and again on 2026-10-08. The older API-key route no longer works.
When to prefer MCP:
- Creating a task or subtask whose description carries markdown, since
cupt addsends only the plaindescriptionfield - Creating documents and reading or writing their pages
- Searching the workspace by keyword, or filtering tasks across lists by field
- Creating or updating lists and folders
- Task relations, comment threads, chat and reminders
Limitations:
- No dry-run for task completion (always specify correct status)
- No offline mode
- Requires Code Mode MCP to be configured
- No goals, bulk create or update, webhooks, checklist edits, spaces, views, templates, guests, user groups or audit logs. Its operator catalog had nothing enabled on 2026-10-08
Prerequisites:
- Code Mode MCP configured, with the
clickup_officialmanual in.utcp_config.json(notopencode.json, that file is for native/non-Code-Mode MCP tools) - One OAuth approval for ClickUp in the browser, on the first launch
Configuration (.utcp_config.json, manual_call_templates):
{
"name": "clickup_official",
"call_template_type": "mcp",
"config": {
"mcpServers": {
"clickup_official": {
"transport": "stdio",
"command": "npx",
"args": ["-y", "mcp-remote", "https://mcp.clickup.com/mcp"]
}
}
}
}
Reference: references/mcp-tools.md and mcp-servers/clickup-mcp/README.md
Invocation via Code Mode. Call mcp__code_mode__call_tool_chain with one code string, not an array of {tool, input} records.
Every server tool name already starts with clickup_. Its callable name repeats that prefix: clickup_official.clickup_official_clickup_<tool>.
Top-level await is rejected, and a returned value comes back as {}. Wrap calls in an async function and print with console.log:
(async () => {
const doc = await clickup_official.clickup_official_clickup_create_document({
name: "Sprint Notes",
parent: { id: "LIST_ID", type: "6" }, // "4" space, "5" folder, "6" list, "7" everything, "12" workspace
visibility: "PRIVATE",
create_page: false,
});
console.log(JSON.stringify(doc));
})();
The document tool takes no content. Add text with clickup_create_document_page and content_format: "text/md". See references/mcp-tools.md sections 7 and 8.
5. RULES
✅ ALWAYS
- Run
cupt statuses <id>before anycupt donecall — each ClickUp list has its own status schema; the closed status varies (Done, Complete, Closed, etc.). Never assume. - Use
cupt done <id> --dry-runbefore batch completion — verify resolved status for every task before writing. One dry-run per task in a batch loop. - Use
--jsonflag for all cupt read commands when processing output programmatically:cupt list --json,cupt show <id> --json, etc. - Run
cupt --version && cupt statusas preflight before starting a ClickUp workflow session. Read its output, not its exit code: cupt exits 0 even onHTTP 401, and prints the failure as anERROR:line on stderr. - Treat empty
cupt listresults as valid — an empty queue is not an error, unless stderr carries anERROR:line, which means the call failed. Before escalating: check tag spelling, try--allflag, verify team name viacupt teams. - Use
cupt context <id>before acting on a task to understand its parent and sibling relationships. - Route markdown through markdown-aware parameters per the MARKDOWN FORMATTING CONTRACT section at the top of this skill. On the Code Mode manual:
markdown_descriptionfor task create and update,content_format: "text/md"for document pages, andinclude: ["description"]onclickup_get_taskfor read-back.
⛔ NEVER
- Never hardcode status names across tasks —
"Done"in one list may not exist in another. Usecupt statuses <id>to discover the correct status for each task's list. - Never run
cupt doneon multiple tasks without per-task dry-run first — batch status errors are hard to reverse. - Never use
@krodak/clickup-cli(cucommand) — this is a different tool not supported by this skill. Thecubinary also conflicts with the systemcucommand on some Unix systems. - Never auto-modify
opencode.json— print MCP config snippets for user to apply; never write to config files programmatically. - Never fabricate tasks — if
cupt listreturns empty, the queue is genuinely empty. Report this clearly. - Never use the MCP for daily task ops — cupt handles these more efficiently and with dry-run safety.
- Never put markdown into the plain
descriptionfield — it renders as literal### Heading/**bold**/- [ ]text in ClickUp. Any content containing markdown syntax must use the markdown-aware parameters from ALWAYS rule 7. This is exactly the defect that produced raw-markdown tickets in the Barter workspace.
⚠️ ESCALATE IF
- cupt is not installed and
scripts/install.shfails → report Python version and pip issues cupt statusshows auth failure → direct tocupt authorcupt config --api-tokencupt list --team Xis extremely slow (>30s) → team filter is client-side on large workspaces; suggest combining with--tagto reduce result set- MCP connection fails → verify the
clickup_officialmanual in.utcp_config.jsonlaunchesnpx -y mcp-remote https://mcp.clickup.com/mcpover stdio, and that the OAuth approval is still valid. Anot_found_or_authorizederror on every call means the approval has lapsed, so approve again. The same error on one page means that page is missing or restricted - Task status after
cupt doneis unexpected → runcupt statuses <id>and report available statuses
6. SUCCESS CRITERIA
-
cupt --versionprints version string -
cupt statusshows workspace name without error -
cupt list --today --jsonreturns 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-runshows resolved status - For MCP operations: Code Mode
clickup_official.clickup_official_clickup_get_workspace_hierarchyreturns the workspace's spaces
7. 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_official.clickup_official_clickup_{tool}, because every server tool name already starts with clickup_. See references/mcp-tools.md for the full tool catalog.
Memory: Save ClickUp workflow context (current list, active tags, workspace ID) using /speckit: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.
8. 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 |
9. REFERENCES AND RELATED RESOURCES
Reference Files (load on demand via router):
references/cupt-commands.md— Full cupt command reference with agent patternsreferences/mcp-tools.md: the 67 live MCP tools, invocation, markdown contract and what the server cannot doreferences/troubleshooting.md— Auth, status, team-filter, MCP failures- INSTALL-GUIDE.md: the condensed top-level install front door at the packet root, with step-by-step install and validation checkpoints, and the router's INSTALL-intent target
Scripts:
scripts/install.sh— Installs cupt + prints MCP config snippet
Embedded Servers:
mcp-servers/clickup-mcp/README.md— Configuration notes for the hosted official server, reached throughmcp-remoteby theclickup_officialmanual.mcp-servers/clickup-cli/requirements.txt— cupt CLI pip pin (cupt>=0.7.1). Runsetup.shto install.mcp-servers/clickup-cli/setup.sh— cupt install via pipx or pip.
Examples:
examples/task-queue-workflow.sh— Process tagged work queueexamples/time-tracking-workflow.sh— Timer + time log workflow
Related Skills:
mcp-chrome-devtools— Structural template this skill was modeled onmcp-code-mode— Code Mode MCP orchestration (used for official MCP invocation)
External: