使用说明

点击MCP服务器

模型上下文协议（MCP）服务器，提供与ClickUp API的全面集成。此服务器使Claude等LLM能够以编程方式管理任务、项目、团队和工作流。

特性

组织和层次结构

列出团队/工作区
浏览空间、文件夹和列表
获取包括状态和自定义字段在内的列表详细信息

任务管理

创建、读取、更新和删除任务
设置任务状态、优先级、指定人员和截止日期
管理任务描述和详细信息
通过分页处理按状态统计任务
将任务导出为CSV格式

搜索与协作

使用筛选器跨团队搜索任务
添加和检索任务的评论

高级功能

设置自定义字段值
跟踪任务时间
获取时间条目
通过E.164电话号码标准化导出为CSV

安装

来自npm

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

来源

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

配置

环境变量

变量	必填	描述
`CLICKUP_API_TOKEN`	是	您的ClickUp API令牌（以 `pk_`)

获取您的API代币

首选 https://app.clickup.com/settings/apps
在“API代币”下，点击“生成”
复制令牌（它以开头 pk_)
请妥善保管，您将无法再看到它！

设置环境变量

Linux/macOS：

export CLICKUP_API_TOKEN="pk_your_token_here"

Windows（命令提示符）：

set CLICKUP_API_TOKEN=pk_your_token_here

Windows（PowerShell）：

$env:CLICKUP_API_TOKEN="pk_your_token_here"

用法

运行服务器

独立模式：

# If installed globally
clickup-mcp

# If installed from source
npm start

自动重新加载的开发模式：

npm run dev

Claude桌面集成

将以下内容添加到您的Claude Desktop配置文件中：

macOS： ~/Library/Application Support/Claude/claude_desktop_config.json 窗户： %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"
      }
    }
  }
}

使用npx（无需安装）：

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

游标IDE集成

添加到光标MCP设置(.cursor/mcp.json 在项目或全局设置中）：

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

API 参考

组织工具

`clickup_get_teams`

列出经过身份验证的用户可访问的所有团队/工作区。

参数：

名称	类型	必填	描述
`response_format`	`"markdown"`	`"json"`	否

例子：

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

`clickup_get_spaces`

获取团队/工作区中的所有空间。

参数：

名称	类型	必填	描述
`team_id`	string	是	团队/工作区ID
`archived`	boolean	否	包括存档空间（默认值： `false`)
`response_format`	`"markdown"`	`"json"`	否

例子：

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

`clickup_get_folders`

获取空间中的所有文件夹。

参数：

名称	类型	必填	描述
`space_id`	string	是	空间ID
`archived`	boolean	否	包括存档文件夹（默认值： `false`)
`response_format`	`"markdown"`	`"json"`	否

`clickup_get_lists`

获取文件夹或空间中的所有列表。

参数：

名称	类型	必填	描述
`folder_id`	string	否*	文件夹ID
`space_id`	string	否*	空间ID（适用于无文件夹列表）
`archived`	boolean	否	包括存档列表（默认值： `false`)
`response_format`	`"markdown"`	`"json"`	否

*必须提供 folder_id 或 space_id但不是两者都有。

`clickup_get_list_details`

获取特定列表的详细信息，包括可用状态和自定义字段。

参数：

名称	类型	必填	描述
`list_id`	string	是	列表ID
`response_format`	`"markdown"`	`"json"`	否

任务管理工具

`clickup_get_tasks`

使用筛选和分页功能获取特定列表中的任务。

参数：

名称	类型	必填	描述
`list_id`	string	是	列表ID
`archived`	boolean	否	包括已存档的任务（默认值： `false`)
`include_closed`	boolean	否	包括已关闭的任务（默认值： `false`)
`statuses`	string[]	否	按状态名称筛选
`assignees`	number[]	否	按受让人ID筛选
`limit`	number	No	最大结果1-100（默认值： `20`)
`offset`	number	No	分页偏移量（默认值： `0`)
`response_format`	`"markdown"`	`"json"`	否
`response_mode`	`"full"`	`"compact"`	`"summary"`

例子：

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

`clickup_get_task`

获取特定任务的详细信息。

参数：

名称	类型	必填	描述
`task_id`	string	是	任务ID
`response_format`	`"markdown"`	`"json"`	否

`clickup_create_task`

在列表中创建新任务。

参数：

名称	类型	必填	描述
`list_id`	string	是	列表ID
`name`	string	是	任务名称
`description`	string	否	任务描述（支持markdown）
`status`	string	否	任务状态（必须与列表状态匹配）
`priority`	1-4	否	优先级：1=紧急，2=高，3=正常，4=低
`assignees`	number[]	否	受让人用户ID
`due_date`	number	No	到期日期（Unix时间戳，单位为毫秒）
`start_date`	number	No	开始日期（Unix时间戳，单位为毫秒）
`tags`	string[]	否	标记名称
`response_format`	`"markdown"`	`"json"`	否

例子：

{
  "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`

更新现有任务的属性。

参数：

名称	类型	必填	描述
`task_id`	string	是	任务ID
`name`	string	否	新任务名称
`description`	string	否	新描述
`status`	string	否	新状态
`priority`	1-4	否	新优先级
`assignees_add`	number[]	否	要添加为受让人的用户ID
`assignees_rem`	number[]	否	要从受让人中删除的用户ID
`due_date`	number	否	新的到期日期（Unix时间戳）
`response_format`	`"markdown"`	`"json"`	否

例子：

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

`clickup_delete_task`

永久删除任务。 ⚠️ 此操作无法撤消。

参数：

名称	类型	必填	描述
`task_id`	string	是	要删除的任务ID

`clickup_count_tasks_by_status`

按状态统计列表中的任务。内部处理分页以进行准确计数。

参数：

名称	类型	必填	描述
`list_id`	string	是	列表ID
`statuses`	string[]	否	按特定状态名称筛选
`archived`	boolean	否	包括已存档的任务（默认值： `false`)
`include_closed`	boolean	否	包括已关闭的任务（默认值： `false`)
`response_format`	`"markdown"`	`"json"`	否

例子：

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

`clickup_export_tasks_to_csv`

使用自定义字段支持将任务从列表导出为CSV格式。

参数：

名称	类型	必填	描述
`list_id`	string	是	列表ID
`statuses`	string[]	否	按状态名称筛选
`archived`	boolean	否	包括已存档的任务（默认值： `false`)
`include_closed`	boolean	否	包括已关闭的任务（默认值： `false`)
`custom_fields`	string[]	否	要包含的特定自定义字段名称
`include_standard_fields`	boolean	否	包括标准字段（默认值： `true`)
`add_phone_number_column`	boolean	否	添加E.164格式的电话列（默认值： `false`)

例子：

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

搜索和评论工具

`clickup_search_tasks`

使用高级筛选在整个团队中搜索任务。

参数：

名称	类型	必填	描述
`team_id`	string	是	要搜索的团队ID
`query`	string	否	搜索查询字符串
`statuses`	string[]	否	按状态名称筛选
`assignees`	number[]	否	按受让人ID筛选
`tags`	string[]	否	按标记名筛选
`date_created_gt`	number	否	创建时间（Unix时间戳）
`date_updated_gt`	number	否	更新时间（Unix时间戳）
`limit`	number	No	最大结果1-100（默认值： `20`)
`offset`	number	No	分页偏移量（默认值： `0`)
`response_format`	`"markdown"`	`"json"`	否
`response_mode`	`"full"`	`"compact"`	`"summary"`

例子：

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

`clickup_add_comment`

向任务添加注释。

参数：

名称	类型	必填	描述
`task_id`	string	是	任务ID
`comment_text`	string	是	注释文本（支持markdown）
`notify_all`	boolean	否	通知所有任务观察者（默认值： `false`)

例子：

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

`clickup_get_comments`

获取任务的所有评论。

参数：

名称	类型	必填	描述
`task_id`	string	是	任务ID
`response_format`	`"markdown"`	`"json"`	否

高级工具

`clickup_set_custom_field`

为任务设置自定义字段值。

参数：

名称	类型	必填	描述
`task_id`	string	是	任务ID
`field_id`	string	是	自定义字段ID
`value`	任意	是	要设置的值（格式取决于字段类型）

按字段类型列出的值格式：

文本/URL/电子邮件： "string value"
编号/货币： 123
日期： Unix时间戳（毫秒）
下拉菜单： "option_uuid"
复选框： true 或 false

例子：

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

`clickup_start_time_entry`

开始跟踪任务的时间。

参数：

名称	类型	必填	描述
`team_id`	string	是	团队ID
`task_id`	string	是	任务ID
`description`	string	否	工作描述

`clickup_stop_time_entry`

停止当前正在运行的时间条目。

参数：

名称	类型	必填	描述
`team_id`	string	是	团队ID

`clickup_get_time_entries`

获取团队的时间跟踪条目。

参数：

名称	类型	必填	描述
`team_id`	string	是	团队ID
`assignee`	number	否	按受让人用户ID筛选
`start_date`	number	否	日期后筛选器（Unix时间戳）
`end_date`	number	否	日期前筛选（Unix时间戳）
`response_format`	`"markdown"`	`"json"`	否

例子

获取团队结构

"List all my ClickUp teams and their spaces"

助理会打电话来 clickup_get_teams 随后 clickup_get_spaces 对于每个团队。

创建和分配任务

"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]
  }
}

搜索任务

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

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

导出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
  }
}

响应格式

所有工具都支持两种响应格式：

格式	描述	用例
`markdown`	人类可读的格式化文本	默认设置，最适合对话式AI
`json`	结构化JSON数据	程序化处理

响应模式（任务工具）

任务相关工具还支持响应模式：

模式	描述	用例
`full`	完成所有字段的任务详细信息	单个任务检查
`compact`	仅限基本字段（id、姓名、状态、受让人）	大型结果集
`summary`	按状态/受让人统计概述	快速状态报告

速率限制

点击API费率限制因计划而异：

计划	请求/分钟
免费/无限	100
商业	100
商务+	1000
企业	10000

服务器包括对速率限制响应的自动错误处理（HTTP 429）。

发展

先决条件

Node.js 18或更高版本
npm或纱线

建筑

npm run build

运行测试

npm test

覆盖测试

npm run test:coverage

清洁建筑

npm run clean
npm run build

项目结构

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

贡献

分叉存储库
创建功能分支(git checkout -b feature/amazing-feature)
通过适当的测试进行更改
运行棉绒和测试(npm test)
提交您的更改(git commit -m 'Add amazing feature')
推到分支(git push origin feature/amazing-feature)
打开拉取请求

使用说明

点击MCP服务器

目录

特性

组织和层次结构

任务管理

搜索与协作

高级功能

安装

来自npm

来源

配置

环境变量

获取您的API代币

设置环境变量

用法

运行服务器

Claude桌面集成

游标IDE集成

API 参考

组织工具

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

例子

获取团队结构

创建和分配任务

搜索任务

导出CSV

响应格式

响应模式（任务工具）

速率限制

发展

先决条件

建筑

运行测试

覆盖测试

清洁建筑

项目结构

贡献

编码标准

许可证

链接

相关 MCP

GitLab项目管理服务器

Primavera P6 XER文件解析服务器

规范工作流管理工具

协议桥接服务器

React开发协议服务

智能记忆与任务管理服务器

`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`