ClickUp MCP Server

# ClickUp MCP Server Documentation This document provides detailed information about all available tools, their parameters, and usage examples for the ClickUp MCP Server. ## Table of Contents - [Task Management](#task-management) - [List Management](#list-management) - [Folder Management](#folder-management) - [Workspace Organization](#workspace-organization) - [Prompts](#prompts) - [Common Parameters](#common-parameters) - [Error Handling](#error-handling) ## Task Management | Tool | Description | Required Parameters | Optional Parameters | |------|-------------|-------------------|-------------------| | get_tasks | Retrieve tasks from a list | Either `listId` or `listName` | archived, page, order_by, reverse, subtasks, statuses, include_closed, assignees, due_date_gt/lt | | get_task | Get single task details | Either `taskId` or `taskName` | `listName` | | create_task | Create a new task | `name` and either `listId` or `listName` | description, status, priority (1-4), dueDate | | create_bulk_tasks | Create multiple tasks | `tasks[]` | `listId` or `listName` | | update_task | Modify task properties | Either `taskId` or `taskName` | name, description, status, priority, dueDate | | delete_task | Remove a task | `taskId` | `taskName`, `listName` | | move_task | Move task to another list | Either `taskId` or `taskName`, and either `listId` or `listName` | `sourceListName` | | duplicate_task | Copy task to another list | Either `taskId` or `taskName`, and either `listId` or `listName` | `sourceListName` | ### Task Parameters - **Priority Levels**: 1 (Urgent/Highest) to 4 (Low) - **Dates**: Unix timestamps in milliseconds - **Status**: Uses list's default if not specified - **Description**: Supports both plain text and markdown ### Examples #### Creating a Task **User Prompt:** ``` Create a new task in the "Development Tasks" list called "Implement Authentication". It should be high priority and due on January 1st, 2024. Add these requirements: - OAuth2 support - JWT tokens - Refresh token flow ``` **System Response:** ```json { "listName": "Development Tasks", "name": "Implement Authentication", "markdown_description": "## Requirements\n- OAuth2 support\n- JWT tokens\n- Refresh token flow", "priority": 1, "dueDate": 1703980800000 } ``` #### Moving a Task **User Prompt:** ``` Move the "Bug Fix" task from the "Sprint Backlog" list to "Current Sprint" list ``` **System Response:** ```json { "taskName": "Bug Fix", "sourceListName": "Sprint Backlog", "destinationListName": "Current Sprint" } ``` #### Updating Task Status **User Prompt:** ``` Update the "Bug Fix" task status to "Done" ``` **System Response:** ```json { "taskName": "Bug Fix", "status": "Done" } ``` #### Bulk Creating Tasks **User Prompt:** ``` Create these tasks in the "Sprint Backlog" list: 1. Set up CI/CD pipeline (high priority) 2. Write unit tests (normal priority) 3. Update documentation (low priority) ``` **System Response:** ```json { "listName": "Sprint Backlog", "tasks": [ { "name": "Set up CI/CD pipeline", "priority": 2 }, { "name": "Write unit tests", "priority": 3 }, { "name": "Update documentation", "priority": 4 } ] } ``` ## List Management | Tool | Description | Required Parameters | Optional Parameters | |------|-------------|-------------------|-------------------| | create_list | Create a new list | `name` and either `spaceId` or `spaceName` | content, dueDate, priority, assignee | | create_list_in_folder | Create list in folder | `name` and either `folderId` or `folderName` | content, status | | get_list | Get list details | Either `listId` or `listName` | None | | update_list | Update list properties | Either `listId` or `listName` | name, content, status | | delete_list | Delete a list | Either `listId` or `listName` | None | ### List Parameters - **Content**: Description or purpose of the list - **Priority**: Same scale as tasks (1-4) - **Status**: Initial status for the list ### Examples #### Getting List Details **User Prompt:** ``` Get details for the "Sprint Backlog" list ``` **System Response:** ```json { "listName": "Sprint Backlog" } ``` #### Updating a List **User Prompt:** ``` Update the "Sprint Backlog" list to have the description "Current sprint planning items and priorities" ``` **System Response:** ```json { "listName": "Sprint Backlog", "content": "Current sprint planning items and priorities" } ``` ## Folder Management | Tool | Description | Required Parameters | Optional Parameters | |------|-------------|-------------------|-------------------| | create_folder | Create a new folder | `name` and either `spaceId` or `spaceName` | override_statuses | | get_folder | Get folder details | Either `folderId` or `folderName` | `spaceId` or `spaceName` (if using `folderName`) | | update_folder | Update folder properties | Either `folderId` or `folderName` | name, override_statuses, `spaceId` or `spaceName` (if using `folderName`) | | delete_folder | Delete a folder | Either `folderId` or `folderName` | `spaceId` or `spaceName` (if using `folderName`) | ### Folder Parameters - **override_statuses**: Boolean to determine if folder should use custom statuses - **name**: Display name for the folder ### Examples #### Getting Folder Details **User Prompt:** ``` Get details for the "Development Projects" folder ``` **System Response:** ```json { "folderName": "Development Projects" } ``` #### Updating a Folder **User Prompt:** ``` Update the "Development Projects" folder to be named "Active Development Projects" ``` **System Response:** ```json { "folderName": "Development Projects", "name": "Active Development Projects" } ``` ## Workspace Organization | Tool | Description | Required Parameters | Response | |------|-------------|-------------------|----------| | get_workspace_hierarchy | Get complete structure | None | Full workspace tree with spaces, folders, and lists | ### Workspace Tree Structure ```json { "workspace": { "id": "team_id", "name": "Workspace Name", "spaces": [{ "id": "space_id", "name": "Space Name", "lists": [...], "folders": [{ "id": "folder_id", "name": "Folder Name", "lists": [...] }] }] } } ``` ## Prompts | Prompt | Purpose | Features | |--------|---------|----------| | summarize_tasks | Generate task overview | Status summary, relationships, current states | | analyze_priorities | Review task priorities | Priority review, adjustments, sequencing | | generate_description | Create task descriptions | Structure, objectives, dependencies | ## Common Parameters ### Name-based Lookup All tools support looking up items by name instead of ID: - `listName` instead of `listId` - `taskName` instead of `taskId` - `spaceName` instead of `spaceId` - `folderName` instead of `folderId` ### Date Formats - All dates should be provided as Unix timestamps in milliseconds - Example: `1703980800000` for January 1, 2024 ### Priority Levels 1. Urgent/Highest 2. High 3. Normal 4. Low ## Error Handling The server provides clear error messages for: - Missing required parameters - Invalid IDs or names - Items not found - Permission issues - API rate limiting ### Common Error Responses ```json { "error": "List with name 'Development' not found", "type": "NOT_FOUND" } ``` ```json { "error": "Either taskId or taskName is required", "type": "MISSING_PARAMETER" } ``` ### Rate Limiting - Automatic handling of ClickUp API rate limits - Built-in retry mechanism with exponential backoff - Status updates during rate limit waits