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

Related MCP server: ClickUp MCP

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
}

list_folders

Lists all folders in a space.

Input:

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

list_lists

Lists all lists in a space or folder.

Input:

{
  "space_id": "789"
}

or

{
  "folder_id": "456"
}

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
}

Task Tools

list_today_tasks

Lists all tasks due today.

Input:

{
  "workspace_id": "123456"
}

or

{
  "list_id": "789"
}

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"
}

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
}

update_task

Updates an existing task.

Input:

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

add_comment

Adds a comment to a task.

Input:

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

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