ClickUp MCP Server

A Model Context Protocol (MCP) server that provides comprehensive integration with the ClickUp API. This server enables LLMs like Claude to manage tasks, projects, teams, and workflows programmatically.

Table of Contents

• Features
• Installation
• Configuration
• Usage
  • Running the Server
  • Claude Desktop Integration
  • Cursor IDE Integration
• API Reference
  • Organization Tools
  • Task Management Tools
  • Search & Comments Tools
  • Advanced Tools
• Examples
• Response Formats
• Rate Limits
• Development
• Contributing
• License
• Links

Features

Organization & Hierarchy

• List teams/workspaces
• Browse spaces, folders, and lists
• Get list details including statuses and custom fields

Task Management

• Create, read, update, and delete tasks
• Set task status, priority, assignees, and due dates
• Manage task descriptions and details
• Count tasks by status with pagination handling
• Export tasks to CSV format

Search & Collaboration

• Search tasks across teams with filters
• Add and retrieve comments on tasks

Advanced Features

• Set custom field values
• Track time on tasks
• Get time entries
• Export to CSV with E.164 phone number normalization

Installation

From npm

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

From source

git clone https://github.com/griffinwork40/clickup-mcp.git
cd clickup-mcp
npm install
npm run build

Configuration

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | CLICKUP_API_TOKEN | Yes | Your ClickUp API token (starts with pk_) |

Getting Your API Token

1. Go to https://app.clickup.com/settings/apps
2. Under "API Token", click "Generate"
3. Copy the token (it starts with pk_)
4. Store it securely - you won't be able to see it again!

Setting the Environment Variable

Linux/macOS:

export CLICKUP_API_TOKEN="pk_your_token_here"

Windows (Command Prompt):

set CLICKUP_API_TOKEN=pk_your_token_here

Windows (PowerShell):

$env:CLICKUP_API_TOKEN="pk_your_token_here"

Usage

Running the Server

Standalone mode:

# If installed globally
clickup-mcp

# If installed from source
npm start

Development mode with auto-reload:

npm run dev

Claude Desktop Integration

Add the following to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

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

Using npx (no installation required):

{
  "mcpServers": {
    "clickup": {
      "command": "npx",
      "args": ["-y", "@griffinwork40/clickup-mcp-server"],
      "env": {
        "CLICKUP_API_TOKEN": "pk_your_token_here"
      }
    }
  }
}

Cursor IDE Integration

Add to your Cursor MCP settings (.cursor/mcp.json in your project or global settings):

{
  "mcpServers": {
    "clickup": {
      "command": "npx",
      "args": ["-y", "@griffinwork40/clickup-mcp-server"],
      "env": {
        "CLICKUP_API_TOKEN": "pk_your_token_here"
      }
    }
  }
}

API Reference

Organization Tools

clickup_get_teams

List all teams/workspaces accessible to the authenticated user.

Parameters: | Name | Type | Required | Description | |------|------|----------|-------------| | response_format | "markdown" | "json" | No | Output format (default: "markdown") |

Example:

{
  "tool": "clickup_get_teams",
  "arguments": {
    "response_format": "json"
  }
}

clickup_get_spaces

Get all spaces in a team/workspace.

Parameters: | Name | Type | Required | Description | |------|------|----------|-------------| | team_id | string | Yes | Team/workspace ID | | archived | boolean | No | Include archived spaces (default: false) | | response_format | "markdown" | "json" | No | Output format (default: "markdown") |

Example:

{
  "tool": "clickup_get_spaces",
  "arguments": {
    "team_id": "123456",
    "archived": false
  }
}

clickup_get_folders

Get all folders in a space.

Parameters: | Name | Type | Required | Description | |------|------|----------|-------------| | space_id | string | Yes | Space ID | | archived | boolean | No | Include archived folders (default: false) | | response_format | "markdown" | "json" | No | Output format (default: "markdown") |

clickup_get_lists

Get all lists in a folder or space.

Parameters: | Name | Type | Required | Description | |------|------|----------|-------------| | folder_id | string | No* | Folder ID | | space_id | string | No* | Space ID (for folderless lists) | | archived | boolean | No | Include archived lists (default: false) | | response_format | "markdown" | "json" | No | Output format (default: "markdown") |

*Must provide either folder_id OR space_id, but not both.

clickup_get_list_details

Get detailed information about a specific list, including available statuses and custom fields.

Parameters: | Name | Type | Required | Description | |------|------|----------|-------------| | list_id | string | Yes | List ID | | response_format | "markdown" | "json" | No | Output format (default: "markdown") |

Task Management Tools

clickup_get_tasks

Get tasks in a specific list with filtering and pagination.

Parameters: | Name | Type | Required | Description | |------|------|----------|-------------| | list_id | string | Yes | List ID | | archived | boolean | No | Include archived tasks (default: false) | | include_closed | boolean | No | Include closed tasks (default: false) | | statuses | string[] | No | Filter by status names | | assignees | number[] | No | Filter by assignee IDs | | limit | number | No | Max results 1-100 (default: 20) | | offset | number | No | Pagination offset (default: 0) | | response_format | "markdown" | "json" | No | Output format (default: "markdown") | | response_mode | "full" | "compact" | "summary" | No | Detail level (default: "full") |

Example:

{
  "tool": "clickup_get_tasks",
  "arguments": {
    "list_id": "123456",
    "statuses": ["in progress", "review"],
    "response_mode": "compact",
    "limit": 50
  }
}

clickup_get_task

Get detailed information about a specific task.

Parameters: | Name | Type | Required | Description | |------|------|----------|-------------| | task_id | string | Yes | Task ID | | response_format | "markdown" | "json" | No | Output format (default: "markdown") |

clickup_create_task

Create a new task in a list.

Parameters: | Name | Type | Required | Description | |------|------|----------|-------------| | list_id | string | Yes | List ID | | name | string | Yes | Task name | | description | string | No | Task description (markdown supported) | | status | string | No | Task status (must match list statuses) | | priority | 1-4 | No | Priority: 1=Urgent, 2=High, 3=Normal, 4=Low | | assignees | number[] | No | Assignee user IDs | | due_date | number | No | Due date (Unix timestamp in milliseconds) | | start_date | number | No | Start date (Unix timestamp in milliseconds) | | tags | string[] | No | Tag names | | response_format | "markdown" | "json" | No | Output format (default: "markdown") |

Example:

{
  "tool": "clickup_create_task",
  "arguments": {
    "list_id": "123456",
    "name": "Implement user authentication",
    "description": "Add OAuth2 login support for Google and GitHub",
    "priority": 2,
    "status": "to do",
    "assignees": [12345678],
    "tags": ["feature", "security"]
  }
}

clickup_update_task

Update an existing task's properties.

Parameters: | Name | Type | Required | Description | |------|------|----------|-------------| | task_id | string | Yes | Task ID | | name | string | No | New task name | | description | string | No | New description | | status | string | No | New status | | priority | 1-4 | No | New priority | | assignees_add | number[] | No | User IDs to add as assignees | | assignees_rem | number[] | No | User IDs to remove from assignees | | due_date | number | No | New due date (Unix timestamp) | | response_format | "markdown" | "json" | No | Output format (default: "markdown") |

Example:

{
  "tool": "clickup_update_task",
  "arguments": {
    "task_id": "abc123",
    "status": "in progress",
    "priority": 1,
    "assignees_add": [12345678]
  }
}

clickup_delete_task

Delete a task permanently. ⚠️ This action cannot be undone.

Parameters: | Name | Type | Required | Description | |------|------|----------|-------------| | task_id | string | Yes | Task ID to delete |

clickup_count_tasks_by_status

Count tasks in a list by status. Handles pagination internally for accurate counts.

Parameters: | Name | Type | Required | Description | |------|------|----------|-------------| | list_id | string | Yes | List ID | | statuses | string[] | No | Filter by specific status names | | archived | boolean | No | Include archived tasks (default: false) | | include_closed | boolean | No | Include closed tasks (default: false) | | response_format | "markdown" | "json" | No | Output format (default: "markdown") |

Example:

{
  "tool": "clickup_count_tasks_by_status",
  "arguments": {
    "list_id": "123456",
    "statuses": ["#1 - phone call", "#2 - follow up"]
  }
}

clickup_export_tasks_to_csv

Export tasks from a list to CSV format with custom field support.

Parameters: | Name | Type | Required | Description | |------|------|----------|-------------| | list_id | string | Yes | List ID | | statuses | string[] | No | Filter by status names | | archived | boolean | No | Include archived tasks (default: false) | | include_closed | boolean | No | Include closed tasks (default: false) | | custom_fields | string[] | No | Specific custom field names to include | | include_standard_fields | boolean | No | Include standard fields (default: true) | | add_phone_number_column | boolean | No | Add E.164 formatted phone column (default: false) |

Example:

{
  "tool": "clickup_export_tasks_to_csv",
  "arguments": {
    "list_id": "123456",
    "statuses": ["#1 - phone call"],
    "custom_fields": ["Email", "Company", "Phone"],
    "add_phone_number_column": true
  }
}

Search & Comments Tools

clickup_search_tasks

Search for tasks across a team with advanced filtering.

Parameters: | Name | Type | Required | Description | |------|------|----------|-------------| | team_id | string | Yes | Team ID to search in | | query | string | No | Search query string | | statuses | string[] | No | Filter by status names | | assignees | number[] | No | Filter by assignee IDs | | tags | string[] | No | Filter by tag names | | date_created_gt | number | No | Created after (Unix timestamp) | | date_updated_gt | number | No | Updated after (Unix timestamp) | | limit | number | No | Max results 1-100 (default: 20) | | offset | number | No | Pagination offset (default: 0) | | response_format | "markdown" | "json" | No | Output format (default: "markdown") | | response_mode | "full" | "compact" | "summary" | No | Detail level (default: "full") |

Example:

{
  "tool": "clickup_search_tasks",
  "arguments": {
    "team_id": "123456",
    "query": "authentication",
    "statuses": ["in progress", "to do"],
    "response_mode": "compact"
  }
}

clickup_add_comment

Add a comment to a task.

Parameters: | Name | Type | Required | Description | |------|------|----------|-------------| | task_id | string | Yes | Task ID | | comment_text | string | Yes | Comment text (markdown supported) | | notify_all | boolean | No | Notify all task watchers (default: false) |

Example:

{
  "tool": "clickup_add_comment",
  "arguments": {
    "task_id": "abc123",
    "comment_text": "Great progress! Ready for review.",
    "notify_all": true
  }
}

clickup_get_comments

Get all comments on a task.

Parameters: | Name | Type | Required | Description | |------|------|----------|-------------| | task_id | string | Yes | Task ID | | response_format | "markdown" | "json" | No | Output format (default: "markdown") |

Advanced Tools

clickup_set_custom_field

Set a custom field value on a task.

Parameters: | Name | Type | Required | Description | |------|------|----------|-------------| | task_id | string | Yes | Task ID | | field_id | string | Yes | Custom field ID | | value | any | Yes | Value to set (format depends on field type) |

Value formats by field type:

• Text/URL/Email: "string value"
• Number/Currency: 123
• Date: Unix timestamp in milliseconds
• Dropdown: "option_uuid"
• Checkbox: true or false

Example:

{
  "tool": "clickup_set_custom_field",
  "arguments": {
    "task_id": "abc123",
    "field_id": "cf_123456",
    "value": "completed"
  }
}

clickup_start_time_entry

Start tracking time on a task.

Parameters: | Name | Type | Required | Description | |------|------|----------|-------------| | team_id | string | Yes | Team ID | | task_id | string | Yes | Task ID | | description | string | No | Description of work |

clickup_stop_time_entry

Stop the currently running time entry.

Parameters: | Name | Type | Required | Description | |------|------|----------|-------------| | team_id | string | Yes | Team ID |

clickup_get_time_entries

Get time tracking entries for a team.

Parameters: | Name | Type | Required | Description | |------|------|----------|-------------| | team_id | string | Yes | Team ID | | assignee | number | No | Filter by assignee user ID | | start_date | number | No | Filter after date (Unix timestamp) | | end_date | number | No | Filter before date (Unix timestamp) | | response_format | "markdown" | "json" | No | Output format (default: "markdown") |

Examples

Get Team Structure

"List all my ClickUp teams and their spaces"

The assistant will call clickup_get_teams followed by clickup_get_spaces for each team.

Create and Assign a Task

"Create a task called 'Fix login bug' in list 123456, assign it to user 789, and set it as urgent"

{
  "tool": "clickup_create_task",
  "arguments": {
    "list_id": "123456",
    "name": "Fix login bug",
    "priority": 1,
    "assignees": [789]
  }
}

Search for Tasks

"Find all in-progress tasks about authentication in team 123456"

{
  "tool": "clickup_search_tasks",
  "arguments": {
    "team_id": "123456",
    "query": "authentication",
    "statuses": ["in progress"]
  }
}

Export Leads to CSV

"Export all leads with status '#1 - phone call' from list 123456 to CSV with phone numbers"

{
  "tool": "clickup_export_tasks_to_csv",
  "arguments": {
    "list_id": "123456",
    "statuses": ["#1 - phone call"],
    "add_phone_number_column": true
  }
}

Response Formats

All tools support two response formats:

| Format | Description | Use Case | |--------|-------------|----------| | markdown | Human-readable formatted text | Default, best for conversational AI | | json | Structured JSON data | Programmatic processing |

Response Modes (Task Tools)

Task-related tools also support response modes:

| Mode | Description | Use Case | |------|-------------|----------| | full | Complete task details with all fields | Individual task inspection | | compact | Essential fields only (id, name, status, assignees) | Large result sets | | summary | Statistical overview by status/assignee | Quick status reports |

Rate Limits

ClickUp API rate limits vary by plan:

| Plan | Requests/Minute | |------|-----------------| | Free/Unlimited | 100 | | Business | 100 | | Business Plus | 1,000 | | Enterprise | 10,000 |

The server includes automatic error handling for rate limit responses (HTTP 429).

Development

Prerequisites

• Node.js 18 or higher
• npm or yarn

Building

npm run build

Running Tests

npm test

Test with Coverage

npm run test:coverage

Clean Build

npm run clean
npm run build

Project Structure

clickup-mcp/
├── src/
│   ├── index.ts      # MCP server entry point and tool definitions
│   ├── constants.ts  # Configuration constants and enums
│   ├── types.ts      # TypeScript type definitions
│   └── utils.ts      # Utility functions for API and formatting
├── dist/             # Compiled JavaScript output
├── package.json
├── tsconfig.json
└── README.md

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Make your changes with appropriate tests
4. Run lint and tests (npm test)
5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

Coding Standards

• Use TypeScript strict mode
• Include JSDoc comments for all public functions
• Follow existing code style and patterns
• Write tests for new functionality

License

MIT License - see LICENSE file for details.

Links

• ClickUp API Documentation
• Model Context Protocol
• MCP TypeScript SDK
• npm Package
• GitHub Repository