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

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.