New:Introducing Socket Scanning for VS Code Marketplace Extensions.Learn more →

@griffinwork40/clickup-mcp-server

Dependencies

Maintainers

Versions

Alerts

File Explorer

Advanced tools

License

Install Socket

Detect and block malicious and high-risk dependencies

Install

@griffinwork40/clickup-mcp-server

MCP server for ClickUp API integration - manage tasks, projects, and workflows

latest

Source

npm

Version: 1.1.6

Version published: 10 months ago

Maintainers: 1

Created: 11 months ago

Source

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.

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

Go to https://app.clickup.com/settings/apps
Under "API Token", click "Generate"
Copy the token (it starts with pk_)
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

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Make your changes with appropriate tests
Run lint and tests (npm test)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
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.

Keywords

mcp

clickup

model-context-protocol

task-management

project-management

FAQs

What is @griffinwork40/clickup-mcp-server?

Is @griffinwork40/clickup-mcp-server well maintained?

Package last updated on 28 Dec 2025

@griffinwork40/clickup-mcp-server

ClickUp MCP Server

Table of Contents

Features

Organization & Hierarchy

Task Management

Search & Collaboration

Advanced Features

Installation

From npm

From source

Configuration

Environment Variables

Getting Your API Token

Setting the Environment Variable

Usage

Running the Server

Claude Desktop Integration

Cursor IDE Integration

API Reference

Organization Tools

clickup_get_teams

clickup_get_spaces

clickup_get_folders

clickup_get_lists

clickup_get_list_details

Task Management Tools

clickup_get_tasks

clickup_get_task

clickup_create_task

clickup_update_task

clickup_delete_task

clickup_count_tasks_by_status

clickup_export_tasks_to_csv

Search & Comments Tools

clickup_search_tasks

clickup_add_comment

clickup_get_comments

Advanced Tools

clickup_set_custom_field

clickup_start_time_entry

clickup_stop_time_entry

clickup_get_time_entries

Examples

Get Team Structure

Create and Assign a Task

Search for Tasks

Export Leads to CSV

Response Formats

Response Modes (Task Tools)

Rate Limits

Development

Prerequisites

Building

Running Tests

Test with Coverage

Clean Build

Project Structure

Contributing

Coding Standards

License

Links

Keywords

Related posts

Socket Threat Intel Now Shows Which Malware Campaigns Were Blocked or Detected

eMudhra, Brotli, and the Long Tail of a Security Fix

`clickup_get_teams`

`clickup_get_spaces`

`clickup_get_folders`

`clickup_get_lists`

`clickup_get_list_details`

`clickup_get_tasks`

`clickup_get_task`

`clickup_create_task`

`clickup_update_task`

`clickup_delete_task`

`clickup_count_tasks_by_status`

`clickup_export_tasks_to_csv`

`clickup_search_tasks`

`clickup_add_comment`

`clickup_get_comments`

`clickup_set_custom_field`

`clickup_start_time_entry`

`clickup_stop_time_entry`

`clickup_get_time_entries`