# ClickUp MCP Server

A Model Context Protocol (MCP) server that integrates with the ClickUp API, enabling AI assistants to manage tasks across your entire ClickUp workspace hierarchy.

## Features

### Discovery Operations
- **list_workspaces** - List all workspaces/teams you have access to
- **list_spaces** - List all spaces in a workspace
- **list_folders** - List all folders in a space
- **list_lists** - List all lists in a space or folder
- **search_tasks** - Search tasks across a workspace with filters

### Read Operations
- **list_today_tasks** - Retrieve all tasks due today (workspace-wide or list-specific)
- **list_overdue_tasks** - Retrieve all tasks past their due date
- **list_no_due_date_tasks** - Retrieve all tasks without a due date

### Write Operations
- **create_task** - Create a new task with optional description, due date, priority, and assignee
- **update_task** - Update task status, due date, or priority
- **add_comment** - Add a comment to an existing task

## Prerequisites

- Node.js v20 or higher
- A ClickUp account with API access
- A ClickUp API token

## Installation

1. Clone this repository:
   ```bash
   git clone <repository-url>
   cd clickup-mcp
   ```

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

3. Create a `.env` file from the example:
   ```bash
   cp .env.example .env
   ```

4. Configure your environment variables in `.env`:
   ```
   CLICKUP_API_TOKEN=your_api_token_here
   ```

## Getting ClickUp Credentials

### API Token
1. Go to ClickUp Settings (click your avatar → Settings)
2. Navigate to "Apps" in the sidebar
3. Click "Generate" under "API Token"
4. Copy the generated token

## Usage

### Development Mode
```bash
npm run dev
```

### Production Build
```bash
npm run build
npm start
```

## MCP Integration

### Claude Desktop Configuration

Add this server to your Claude Desktop configuration file:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "clickup": {
      "command": "node",
      "args": ["/path/to/clickup-mcp/dist/index.js"],
      "env": {
        "CLICKUP_API_TOKEN": "your_api_token_here"
      }
    }
  }
}
```

Or for development:

```json
{
  "mcpServers": {
    "clickup": {
      "command": "npx",
      "args": ["tsx", "/path/to/clickup-mcp/src/index.ts"],
      "env": {
        "CLICKUP_API_TOKEN": "your_api_token_here"
      }
    }
  }
}
```

## Typical Workflow

The server supports a hierarchical discovery flow:

```
Workspaces → Spaces → Folders → Lists → Tasks
```

### Example Conversation

**User**: "What tasks do I have due today?"

**AI**: 
1. First, let me discover your ClickUp structure...
   ```
   → list_workspaces
   Found: "Acme Corp" (workspace_id: "123")
   ```

2. Searching for today's tasks across the workspace...
   ```
   → list_today_tasks({ workspace_id: "123" })
   Found 5 tasks due today
   ```

**User**: "Create a new task in my Engineering sprint backlog"

**AI**:
1. Let me find that list...
   ```
   → list_spaces({ workspace_id: "123" })
   Found: "Engineering" (space_id: "456")
   
   → list_lists({ space_id: "456" })
   Found: "Sprint Backlog" (list_id: "789")
   ```

2. Creating the task...
   ```
   → create_task({ list_id: "789", name: "New Task" })
   Created successfully!
   ```

## Tool Reference

### Discovery Tools

#### list_workspaces

Lists all workspaces/teams you have access to.

**Input**: None

**Output**:
```json
{
  "count": 2,
  "workspaces": [
    {
      "id": "123456",
      "name": "My Workspace",
      "color": "#7B68EE",
      "members_count": 5
    }
  ]
}
```

#### list_spaces

Lists all spaces in a workspace.

**Input**:
```json
{
  "workspace_id": "123456",
  "include_archived": false
}
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| workspace_id | string | Yes | Workspace ID |
| include_archived | boolean | No | Include archived spaces (default: false) |

#### list_folders

Lists all folders in a space.

**Input**:
```json
{
  "space_id": "789",
  "include_archived": false
}
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| space_id | string | Yes | Space ID |
| include_archived | boolean | No | Include archived folders (default: false) |

#### list_lists

Lists all lists in a space or folder.

**Input**:
```json
{
  "space_id": "789"
}
```
or
```json
{
  "folder_id": "456"
}
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| space_id | string | One required | Space ID (gets all lists including folderless) |
| folder_id | string | One required | Folder ID (gets only lists in folder) |
| include_archived | boolean | No | Include archived lists (default: false) |

#### search_tasks

Search tasks across a workspace with optional filters.

**Input**:
```json
{
  "workspace_id": "123456",
  "query": "bug fix",
  "space_ids": ["789"],
  "statuses": ["in progress"],
  "include_closed": false
}
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| workspace_id | string | Yes | Workspace ID |
| query | string | No | Search query |
| space_ids | string[] | No | Filter by spaces |
| folder_ids | string[] | No | Filter by folders |
| list_ids | string[] | No | Filter by lists |
| statuses | string[] | No | Filter by statuses |
| assignee_ids | number[] | No | Filter by assignees |
| include_closed | boolean | No | Include closed tasks |

### Task Tools

#### list_today_tasks

Lists all tasks due today.

**Input**:
```json
{
  "workspace_id": "123456"
}
```
or
```json
{
  "list_id": "789"
}
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| workspace_id | string | One required | Search across workspace |
| list_id | string | One required | Search specific list |

#### list_overdue_tasks

Lists all overdue tasks. Same input as `list_today_tasks`.

#### list_no_due_date_tasks

Lists all tasks without a due date in a specific list.

**Input**:
```json
{
  "list_id": "789"
}
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| list_id | string | Yes | List ID |

#### create_task

Creates a new task in a specific list.

**Input**:
```json
{
  "list_id": "789",
  "name": "Task Name",
  "description": "Optional description",
  "due_date": "2024-12-31T23:59:59Z",
  "priority": "2",
  "assignee": 12345678
}
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| list_id | string | Yes | List ID to create task in |
| name | string | Yes | Task name |
| description | string | No | Task description |
| due_date | string | No | ISO 8601 date |
| priority | string | No | 1=Urgent, 2=High, 3=Normal, 4=Low |
| assignee | number | No | ClickUp user ID |

#### update_task

Updates an existing task.

**Input**:
```json
{
  "task_id": "abc123",
  "status": "complete",
  "due_date": "2024-12-31T23:59:59Z",
  "priority": "1"
}
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| task_id | string | Yes | Task ID to update |
| status | string | No | New status |
| due_date | string | No | New due date (ISO 8601) |
| priority | string | No | New priority |

#### add_comment

Adds a comment to a task.

**Input**:
```json
{
  "task_id": "abc123",
  "comment": "This is a comment"
}
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| task_id | string | Yes | Task ID |
| comment | string | Yes | Comment text |

## Error Handling

The server provides detailed error responses:

```json
{
  "error": "ClickUp API error",
  "status_code": 401,
  "message": "ClickUp API error: 401 Unauthorized",
  "details": { ... }
}
```

Common error scenarios:
- **401**: Invalid API token
- **404**: Task, list, folder, space, or workspace not found
- **400**: Invalid request parameters
- **Validation error**: Invalid input format

## Project Structure

```
clickup-mcp/
├─ src/
│  ├─ index.ts        # MCP server entry point
│  ├─ clickup.ts      # ClickUp API wrapper
│  ├─ tools.ts        # MCP tool definitions
├─ dist/              # Compiled JavaScript (after build)
├─ package.json
├─ tsconfig.json
├─ .env.example
└─ README.md
```

## Development

### Type Checking
```bash
npx tsc --noEmit
```

### Building
```bash
npm run build
```

## License

MIT