# 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)
```bash
npx @taazkareem/clickup-mcp-server
```

### Global Installation
```bash
npm install -g @taazkareem/clickup-mcp-server
```

## Configuration

1. Get your ClickUp API key from [ClickUp Settings](https://app.clickup.com/settings/apps)
2. Create a `.env` file:
```env
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:

```bash
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](https://app.clickup.com/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:
```bash
git clone https://github.com/taazkareem/clickup-mcp-server.git
cd clickup-mcp-server
```

2. Install dependencies:
```bash
npm install
```

3. Start in development mode:
```bash
npm run dev
```

## Contributing

Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) for details.

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.