ClickUp MCP Server

ClickUp

Project management platform with a strict 5-level hierarchy. Every query requires the parent ID from the level above.

Entity Hierarchy

The hierarchy is rigid: Team → Space → Folder → List → Task. You must walk it top-down because each level's ID is required to query the next.

• Teams (workspaces) — top-level container. Enumerate teams first to get team_id. Also scopes goals, custom fields, and time tracking tags.
• Users — current authenticated user profile. Separate from team context.
• Spaces — project-level containers within a team. Requires team_id. Also scopes tags.
• Folders — optional grouping layer within a space. Requires space_id. Can be skipped (folderless lists exist).
• Lists — task containers. Requires folder_id (or space_id for folderless lists). Scopes comments, custom fields, and task statuses.
• Tasks — individual work items within a list. Requires list_id. Filter by statuses, assignees, and subtasks. Sort with order_by (created/updated/due_date). Use include_closed: true to include completed tasks. Open a task by id for full detail payloads.

Cross-cutting Entities

• Comments — attached to lists (by list_id). Task comments are also available.
• Custom Fields — defined at team level (global) or list level (local). Query both to see all available fields.
• Goals — OKR-style objectives scoped to a team (team_id).
• Tags — labels scoped to a space (space_id).
• Time Tracking — time entries on tasks (task_id). Time tracking tags are team-scoped.

Workflows

• Task discovery: Teams → spaces → folders → lists → tasks (with status/assignee filters) → single-task detail when you need description, dependencies, or custom fields.
• Goal review: Teams → team-scoped goals for OKR progress.
• Time audit: Teams → time-tracking tags, then tasks, then per-task time entries.
• Custom field inventory: Team-wide custom field reads first, then list-scoped definitions for overrides.
• Comment review: Lists → list-level comment threads using the list id from the prior step.

Gotchas

• Strict parent ID chain: you cannot skip levels. Tasks need list_id; lists need a folder or a folderless list under a space; spaces need team_id.
• Folderless lists: many workspaces put lists directly under spaces without folders. When folder listings are empty, enumerate folderless lists for that space_id.
• Closed tasks: Task listings hide completed work unless you opt in via include_closed.
• Detail vs summary: list responses stay lightweight; open a task by id when you need description, custom fields, dependencies, or estimates.
• Custom statuses per list: each list can define its own status workflow. Don't assume status names are consistent across lists.
• Rate limit: 100 requests per minute per token.