clickup-mcp

teren-papercutlabs/clickup-mcp

3.2

If you are the rightful owner of clickup-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

The ClickUp MCP Server integrates ClickUp task management with model context protocol, offering robust task operations, search capabilities, and workspace management.

Tools
  1. clickup_create_task

    Create a new task with full configuration

  2. clickup_get_task

    Get detailed task information

  3. clickup_update_task

    Update task properties (partial updates)

  4. clickup_delete_task

    Permanently delete a task

  5. clickup_list_tasks

    List tasks from a specific list with filters

  6. clickup_search_tasks

    Search with flexible scope (workspace/space/folder/list)

  7. clickup_add_comment

    Add a comment to a task

  8. clickup_list_comments

    Get all comments for a task

  9. clickup_add_dependency

    Create task dependency relationship

  10. clickup_remove_dependency

    Remove task dependency

  11. clickup_list_dependencies

    View all dependencies for a task

  12. clickup_get_workspace_structure

    Discover workspace hierarchy

ClickUp MCP Server

MCP server for ClickUp task management integration, providing comprehensive task operations, search capabilities, and workspace management.

Features

  • Task Management: Create, read, update, and delete tasks
  • Search: Flexible search with scope control (workspace/space/folder/list)
  • Comments: Add and list task comments
  • Dependencies: Manage task dependencies and relationships
  • Workspace Discovery: Navigate workspace hierarchy

Installation

From npm

npm install -g @mcp-servers/clickup

From source

git clone <repository>
cd mcp-servers/clickup
npm install
npm run build

Configuration

Getting your ClickUp API Token

  1. Log into ClickUp
  2. Navigate to Settings → Apps
  3. Under API Token, click "Generate" or copy existing token
  4. Save your personal API token

Environment Setup

Set the CLICKUP_API_TOKEN environment variable:

export CLICKUP_API_TOKEN="pk_YOUR_TOKEN_HERE"

MCP Configuration

Add to your MCP settings file (.mcp.json or equivalent):

{
  "servers": {
    "clickup": {
      "command": "mcp-server-clickup",
      "env": {
        "CLICKUP_API_TOKEN": "pk_YOUR_TOKEN_HERE"
      }
    }
  }
}

Usage

Core Task Operations

Create Task
clickup_create_task({
  list_id: "901234567",
  name: "Implement new feature",
  markdown_description: "## Description\n- Feature details\n- Implementation notes",
  priority: 2, // High
  tags: ["feature", "backend"],
  assignees: [123456] // User IDs
})
Get Task Details
clickup_get_task({
  task_id: "abc123"
})
Update Task
clickup_update_task({
  task_id: "abc123",
  status: "in progress",
  priority: 1, // Urgent
  assignees_add: [789012],
  tags_add: ["urgent"]
})
List Tasks
clickup_list_tasks({
  list_id: "901234567",
  page: 0,
  include_closed: false,
  statuses: ["open", "in progress"]
})

Search Operations

Search with Scope Control
// Search in specific list (fastest)
clickup_search_tasks({
  query: "bug",
  scope: "list",
  list_id: "901234567",
  team_id: "123456"
})

// Search entire workspace (broadest)
clickup_search_tasks({
  query: "overdue",
  scope: "workspace",
  team_id: "123456",
  due_date_lt: Date.now()
})

Comments

Add Comment
clickup_add_comment({
  task_id: "abc123",
  comment_text: "Started working on this. ETA 2 hours.",
  notify_all: true
})
List Comments
clickup_list_comments({
  task_id: "abc123"
})

Dependencies

Add Dependency
// Task A waits for Task B
clickup_add_dependency({
  task_id: "taskA",
  depends_on: "taskB"
})

// Task C blocks Task D
clickup_add_dependency({
  task_id: "taskC",
  dependency_of: "taskD"
})
View Dependencies
clickup_list_dependencies({
  task_id: "abc123"
})

Workspace Discovery

Get Full Workspace Structure
clickup_get_workspace_structure()
// Returns hierarchy: Teams → Spaces → Lists

Tool Reference

Task Tools

ToolDescription
clickup_create_taskCreate a new task with full configuration
clickup_get_taskGet detailed task information
clickup_update_taskUpdate task properties (partial updates)
clickup_delete_taskPermanently delete a task
clickup_list_tasksList tasks from a specific list with filters

Search Tools

ToolDescription
clickup_search_tasksSearch with flexible scope (workspace/space/folder/list)

Comment Tools

ToolDescription
clickup_add_commentAdd a comment to a task
clickup_list_commentsGet all comments for a task

Dependency Tools

ToolDescription
clickup_add_dependencyCreate task dependency relationship
clickup_remove_dependencyRemove task dependency
clickup_list_dependenciesView all dependencies for a task

Workspace Tools

ToolDescription
clickup_get_workspace_structureDiscover workspace hierarchy

Best Practices

Performance

  1. Use narrow search scopes: List search is 10x faster than workspace search
  2. Implement pagination: Use page parameter for large result sets
  3. Cache workspace structure: It rarely changes

Task Creation

  1. Always specify list_id - tasks must belong to a list
  2. Use markdown_description for rich formatting
  3. Set meaningful priorities (1=Urgent, 2=High, 3=Normal, 4=Low)
  4. Include time estimates in milliseconds when known

Error Handling

The server passes through raw ClickUp API errors, which include:

  • Invalid list/task IDs
  • Permission errors
  • Rate limiting
  • Validation errors (e.g., invalid status, missing required fields)

Common Patterns

Find tasks assigned to me
// First, get your user ID from workspace structure
const workspace = await clickup_get_workspace_structure();

// Then search for your tasks
clickup_search_tasks({
  query: "",
  scope: "workspace",
  team_id: workspace.teams[0].id,
  assignees: ["your_user_id"]
})
Create task with due date
// Convert natural language to timestamp
const dueDate = new Date("2024-12-31").getTime();

clickup_create_task({
  list_id: "901234567",
  name: "Year-end report",
  due_date: dueDate,
  priority: 2
})

Limitations

  • Maximum 100 tasks per page in list/search operations
  • Custom fields not supported in this version
  • Rate limits apply based on your ClickUp plan
  • Attachments and time tracking not yet implemented

Development

Building from source

npm install
npm run build

Testing locally

CLICKUP_API_TOKEN=your_token npm run dev

Contributing

Contributions welcome! Please ensure:

  • TypeScript types are properly defined
  • Tool descriptions include usage guidelines
  • Error messages are helpful
  • Code follows existing patterns

License

MIT