ClickUp MCP Server

A Model Context Protocol (MCP) server for integrating ClickUp tasks with AI applications. This server allows AI agents to interact with ClickUp tasks, spaces, lists, and folders through a standardized protocol.

Features

• 🔄 Resource Management

  • List and read ClickUp tasks as resources

  • View task details, status, and assignments

  • Access task history and relationships

• 📂 Workspace Organization

  • Create and manage spaces

  • Create, update, and delete folders

  • Create and manage lists (in spaces or folders)

  • Flexible identification using IDs or names

• ✨ Task Operations

  • Create single or bulk tasks

  • Move tasks between lists

  • Duplicate tasks

  • Set priorities and due dates

  • Assign team members

• 📊 Information Retrieval

  • Get complete hierarchy of spaces, folders, and lists with IDs

  • List available statuses

  • Find items by name (case-insensitive)

  • View task relationships

• 🔍 Smart Name Resolution

  • Use names instead of IDs for lists and folders

  • Global search across all spaces

  • Case-insensitive matching

  • Automatic location of items

• 📝 AI Integration

  • Generate task descriptions with AI

  • Summarize tasks and analyze priorities

  • Get AI-powered task recommendations

• 🔒 Security

  • Secure API key management

  • Environment-based configuration

Installation

Using npx (Recommended)

npx @taazkareem/clickup-mcp-server

Global Installation

npm install -g @taazkareem/clickup-mcp-server

Configuration

1. Get your ClickUp API key from ClickUp Settings

2. Create a .env file:

CLICKUP_API_KEY=your_api_key_here
TEAM_ID=your_team_id_here

Using with Cursor AI Composer

To add this server to Cursor AI Composer, follow these steps:

1. Go to the Features section in the settings.

2. Add the following command under MCP Servers:

npx -y @taazkareem/clickup-mcp-server \
  --env CLICKUP_API_KEY=your_api_key_here \
  --env TEAM_ID=your_team_id_here

3. Replace your_api_key_here and your_team_id_here with your actual ClickUp credentials.

4. Click on 'Save' to add the server.

You can get these values from:

• CLICKUP_API_KEY: Get from ClickUp Settings > Apps

• TEAM_ID: Your ClickUp Team ID (found in the URL when viewing your workspace or via API)

Security Note: Your API key will be stored securely and will not be exposed to AI models.

Available Tools

1. workspace_hierarchy

   • Lists complete hierarchy of the ClickUp workspace

   • Shows spaces, folders, and lists with their IDs

   • Shows available statuses for each list

   • Provides a tree view of your workspace organization

   • No parameters required

2. create_task

   • Creates a new task in ClickUp

   • Required parameters:

     • name: Name of the task

   • Optional parameters:

     • listId: ID of the list (optional if listName provided)

     • listName: Name of the list (optional if listId provided)

     • description: Task description

     • status: Task status

     • priority: Priority level (1-4)

     • dueDate: Due date (ISO string)

     • assignees: Array of user IDs

3. create_bulk_tasks

   • Creates multiple tasks simultaneously in a list

   • Required parameters:

     • tasks: Array of task objects, each containing:

       • name: Name of the task (required)

       • description: Task description (optional)

       • status: Task status (optional)

       • priority: Priority level 1-4 (optional)

       • dueDate: Due date ISO string (optional)

       • assignees: Array of user IDs (optional)

   • Optional parameters:

     • listId: ID of the list (optional if listName provided)

     • listName: Name of the list (optional if listId provided)

4. create_list

   • Creates a new list in a space

   • Required parameters:

     • name: Name of the list

   • Optional parameters:

     • spaceId: ID of the space (optional if spaceName provided)

     • spaceName: Name of the space (optional if spaceId provided)

     • content: List description

     • status: List status

     • priority: Priority level (1-4)

     • dueDate: Due date (ISO string)

5. create_folder

   • Creates a new folder in a space

   • Required parameters:

     • name: Name of the folder

   • Optional parameters:

     • spaceId: ID of the space (optional if spaceName provided)

     • spaceName: Name of the space (optional if spaceId provided)

     • override_statuses: Whether to override space statuses

6. create_list_in_folder

   • Creates a new list within a folder

   • Required parameters:

     • name: Name of the list

   • Optional parameters:

     • folderId: ID of the folder (optional if using folderName)

     • folderName: Name of the folder

     • spaceId: ID of the space (required if using folderName)

     • spaceName: Name of the space (alternative to spaceId)

     • content: List description

     • status: List status

7. move_task

   • Moves a task to a different list

   • Required parameters:

     • taskId: ID of the task to move

   • Optional parameters:

     • listId: ID of destination list (optional if listName provided)

     • listName: Name of destination list (optional if listId provided)

8. duplicate_task

   • Creates a copy of a task in a specified list

   • Required parameters:

     • taskId: ID of the task to duplicate

   • Optional parameters:

     • listId: ID of destination list (optional if listName provided)

     • listName: Name of destination list (optional if listId provided)

9. update_task

   • Updates an existing task

   • Required parameters:

     • taskId: ID of the task to update

   • Optional parameters:

     • name: New task name

     • description: New description

     • status: New status

     • priority: New priority level (1-4)

     • dueDate: New due date (ISO string)

Available Prompts

1. summarize_tasks

   • Provides a comprehensive summary of tasks

   • Groups tasks by status

   • Highlights priorities and deadlines

   • Suggests task relationships

2. analyze_priorities

   • Analyzes task priority distribution

   • Identifies misaligned priorities

   • Suggests priority adjustments

   • Recommends task sequencing

3. generate_description

   • Helps generate detailed task descriptions

   • Includes:

     • Clear objectives

     • Success criteria

     • Required resources

     • Dependencies

     • Potential risks

Name Resolution

Most tools support finding items by either ID or name:

• Spaces can be referenced by spaceId or spaceName

• Folders can be referenced by folderId or folderName (with space information)

• Lists can be referenced by listId or found within spaces/folders

Name matching is case-insensitive for convenience.

Error Handling

The server provides clear error messages for common scenarios:

• Missing required parameters

• Invalid IDs or names

• Items not found

• Permission issues

• API errors

Development

1. Clone the repository:

git clone https://github.com/taazkareem/clickup-mcp-server.git
cd clickup-mcp-server

2. Install dependencies:

npm install

3. Start in development mode:

npm run dev

Contributing

Contributions are welcome! Please read our Contributing Guide for details.

License

This project is licensed under the MIT License - see the LICENSE file for details.