ClickUp MCP Server
by v4lheru
Verified
- docs
# 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