ClickUp MCP Server

A Model Context Protocol (MCP) server that integrates with the ClickUp API, enabling AI assistants to manage tasks across your entire ClickUp workspace hierarchy.

Features

Discovery Operations

• list_workspaces - List all workspaces/teams you have access to
• list_spaces - List all spaces in a workspace
• list_folders - List all folders in a space
• list_lists - List all lists in a space or folder
• search_tasks - Search tasks across a workspace with filters

Read Operations

• list_today_tasks - Retrieve all tasks due today (workspace-wide or list-specific)
• list_overdue_tasks - Retrieve all tasks past their due date
• list_no_due_date_tasks - Retrieve all tasks without a due date

Write Operations

• create_task - Create a new task with optional description, due date, priority, and assignee
• update_task - Update task status, due date, or priority
• add_comment - Add a comment to an existing task

Prerequisites

• Node.js v20 or higher
• A ClickUp account with API access
• A ClickUp API token

Installation

1. Clone this repository:

   git clone <repository-url>
   cd clickup-mcp
   

2. Install dependencies:

   npm install
   

3. Create a .env file from the example:

   cp .env.example .env
   

4. Configure your environment variables in .env:

   CLICKUP_API_TOKEN=your_api_token_here
   

Getting ClickUp Credentials

API Token

1. Go to ClickUp Settings (click your avatar → Settings)
2. Navigate to "Apps" in the sidebar
3. Click "Generate" under "API Token"
4. Copy the generated token

Usage

Development Mode

npm run dev

Production Build

npm run build
npm start

MCP Integration

Claude Desktop Configuration

Add this server to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "clickup": {
      "command": "node",
      "args": ["/path/to/clickup-mcp/dist/index.js"],
      "env": {
        "CLICKUP_API_TOKEN": "your_api_token_here"
      }
    }
  }
}

Or for development:

{
  "mcpServers": {
    "clickup": {
      "command": "npx",
      "args": ["tsx", "/path/to/clickup-mcp/src/index.ts"],
      "env": {
        "CLICKUP_API_TOKEN": "your_api_token_here"
      }
    }
  }
}

Typical Workflow

The server supports a hierarchical discovery flow:

Workspaces → Spaces → Folders → Lists → Tasks

Example Conversation

User: "What tasks do I have due today?"

AI:

1. First, let me discover your ClickUp structure...

   → list_workspaces
   Found: "Acme Corp" (workspace_id: "123")
   

2. Searching for today's tasks across the workspace...

   → list_today_tasks({ workspace_id: "123" })
   Found 5 tasks due today
   

User: "Create a new task in my Engineering sprint backlog"

AI:

1. Let me find that list...

   → list_spaces({ workspace_id: "123" })
   Found: "Engineering" (space_id: "456")
   
   → list_lists({ space_id: "456" })
   Found: "Sprint Backlog" (list_id: "789")
   

2. Creating the task...

   → create_task({ list_id: "789", name: "New Task" })
   Created successfully!
   

Tool Reference

Discovery Tools

list_workspaces

Lists all workspaces/teams you have access to.

Input: None

Output:

{
  "count": 2,
  "workspaces": [
    {
      "id": "123456",
      "name": "My Workspace",
      "color": "#7B68EE",
      "members_count": 5
    }
  ]
}

list_spaces

Lists all spaces in a workspace.

Input:

{
  "workspace_id": "123456",
  "include_archived": false
}

Field	Type	Required	Description
workspace_id	string	Yes	Workspace ID
include_archived	boolean	No	Include archived spaces (default: false)

list_folders

Lists all folders in a space.

Input:

{
  "space_id": "789",
  "include_archived": false
}

Field	Type	Required	Description
space_id	string	Yes	Space ID
include_archived	boolean	No	Include archived folders (default: false)

list_lists

Lists all lists in a space or folder.

Input:

{
  "space_id": "789"
}

or

{
  "folder_id": "456"
}

Field	Type	Required	Description
space_id	string	One required	Space ID (gets all lists including folderless)
folder_id	string	One required	Folder ID (gets only lists in folder)
include_archived	boolean	No	Include archived lists (default: false)

search_tasks

Search tasks across a workspace with optional filters.

Input:

{
  "workspace_id": "123456",
  "query": "bug fix",
  "space_ids": ["789"],
  "statuses": ["in progress"],
  "include_closed": false
}

Field	Type	Required	Description
workspace_id	string	Yes	Workspace ID
query	string	No	Search query
space_ids	string[]	No	Filter by spaces
folder_ids	string[]	No	Filter by folders
list_ids	string[]	No	Filter by lists
statuses	string[]	No	Filter by statuses
assignee_ids	number[]	No	Filter by assignees
include_closed	boolean	No	Include closed tasks

Task Tools

list_today_tasks

Lists all tasks due today.

Input:

{
  "workspace_id": "123456"
}

or

{
  "list_id": "789"
}

Field	Type	Required	Description
workspace_id	string	One required	Search across workspace
list_id	string	One required	Search specific list

list_overdue_tasks

Lists all overdue tasks. Same input as list_today_tasks.

list_no_due_date_tasks

Lists all tasks without a due date in a specific list.

Input:

{
  "list_id": "789"
}

Field	Type	Required	Description
list_id	string	Yes	List ID

create_task

Creates a new task in a specific list.

Input:

{
  "list_id": "789",
  "name": "Task Name",
  "description": "Optional description",
  "due_date": "2024-12-31T23:59:59Z",
  "priority": "2",
  "assignee": 12345678
}

Field	Type	Required	Description
list_id	string	Yes	List ID to create task in
name	string	Yes	Task name
description	string	No	Task description
due_date	string	No	ISO 8601 date
priority	string	No	1=Urgent, 2=High, 3=Normal, 4=Low
assignee	number	No	ClickUp user ID

update_task

Updates an existing task.

Input:

{
  "task_id": "abc123",
  "status": "complete",
  "due_date": "2024-12-31T23:59:59Z",
  "priority": "1"
}

Field	Type	Required	Description
task_id	string	Yes	Task ID to update
status	string	No	New status
due_date	string	No	New due date (ISO 8601)
priority	string	No	New priority

add_comment

Adds a comment to a task.

Input:

{
  "task_id": "abc123",
  "comment": "This is a comment"
}

Field	Type	Required	Description
task_id	string	Yes	Task ID
comment	string	Yes	Comment text

Error Handling

The server provides detailed error responses:

{
  "error": "ClickUp API error",
  "status_code": 401,
  "message": "ClickUp API error: 401 Unauthorized",
  "details": { ... }
}

Common error scenarios:

• 401: Invalid API token
• 404: Task, list, folder, space, or workspace not found
• 400: Invalid request parameters
• Validation error: Invalid input format

Project Structure

clickup-mcp/
├─ src/
│  ├─ index.ts        # MCP server entry point
│  ├─ clickup.ts      # ClickUp API wrapper
│  ├─ tools.ts        # MCP tool definitions
├─ dist/              # Compiled JavaScript (after build)
├─ package.json
├─ tsconfig.json
├─ .env.example
└─ README.md

Development

Type Checking

npx tsc --noEmit

Building

npm run build

License

MIT