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

Configuration

1. Get your ClickUp API key from ClickUp Settings
2. Create a .env file:

Using with Cursor AI Composer Agent

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:

3. Replace your_api_key_here and your_team_id_here with your actual ClickUp credentials.
4. Click on 'Save' to add the server.

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:

2. Install dependencies:

3. Start in development mode:

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.