Clickup Integration Mcp Server

ClickUp MCP 服务

一个 Model Context Protocol（MCP）服务，可让 Claude 与 ClickUp 交互以管理任务。通过在 Claude Desktop 中输入自然语言提示词，即可创建、更新和管理 ClickUp 任务。

功能

• 浏览 ClickUp 层级结构：浏览工作区、空间、文件夹和列表
• 任务管理：创建、读取、更新和删除任务
• 高级筛选：按状态、受指派人、标签、截止日期等筛选任务
• 团队协作：查看任务和列表成员
• 丰富的任务属性：支持描述、优先级、受指派人、截止日期、标签和自定义字段

可用工具

导航工具

• get_workspaces - 列出所有可访问的 ClickUp 工作区
• get_spaces - 获取工作区中的空间
• get_folders - 获取空间中的文件夹
• get_lists - 获取空间或文件夹中的列表

任务管理工具

• create_task - 创建具有各种属性的新任务
• get_task - 获取特定任务的详细信息
• get_task_by_custom_id - 使用自定义 ID 获取任务（例如 CUSTOM-123）
• get_tasks - 通过筛选和分页列出任务（包括自定义 ID）
• update_task - 更新任务属性（名称、状态、受指派人等）
• update_task_by_custom_id - 使用自定义 ID 更新任务
• delete_task - 永久删除任务

成员工具

• get_task_members - 获取有权访问某项任务的成员
• get_list_members - 获取有权访问某个列表的成员

安装

前提条件

• Node.js 18 或更高版本
• 拥有 API 访问权限的 ClickUp 账户
• Claude Desktop 应用

1. 克隆并安装

git clone <repository-url>
cd clickup-mcp
npm install

2. 获取 ClickUp API 令牌

1. 登录 ClickUp 账户
2. 点击左下角的个人资料图片
3. 选择 Settings
4. 点击左侧边栏中的 Apps
5. 向下滚动到 API Token 部分
6. 点击 Generate（如果已有令牌，则点击 Regenerate）
7. 复制令牌（以 pk_ 开头）

重要：请妥善保管 API 令牌。切勿将其提交到版本控制系统。

3. 配置环境变量

在项目根目录中创建 .env 文件：

cp .env.example .env

编辑 .env 并添加 ClickUp API 令牌：

CLICKUP_API_TOKEN=pk_your_actual_token_here

4. 构建服务

npm run build

这会将 TypeScript 代码编译为 JavaScript，并输出到 dist/ 目录。

配置 Claude Desktop

Windows

1. 打开 Claude Desktop 配置文件：

   %AppData%\Claude\claude_desktop_config.json
   

2. 添加 ClickUp MCP 服务配置：

{
  "mcpServers": {
    "clickup": {
      "command": "node",
      "args": ["C:\Users\username\Documents\clickup-updater\clickup-mcp\dist\index.js"],
      "env": {
        "CLICKUP_API_TOKEN": "pk_your_actual_token_here"
      }
    }
  }
}

注意：请将路径替换为实际的安装路径。在 Windows 路径中使用双反斜杠（\）。

macOS/Linux

1. 打开 Claude Desktop 配置文件：

   ~/Library/Application Support/Claude/claude_desktop_config.json
   

2. 添加 ClickUp MCP 服务配置：

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

5. 重启 Claude Desktop

更新配置后，重启 Claude Desktop 以加载 MCP 服务。

使用示例

配置完成后，你可以在 Claude 中通过自然语言提示词与 ClickUp 交互：

导航

"Show me all my ClickUp workspaces"

"List the spaces in workspace 12345"

"What lists are in the Marketing space?"

创建任务

"Create a task called 'Review Q1 metrics' in the Marketing Reports list"

"Create a high-priority task for the website redesign project with John and Sarah assigned"

"Add a task 'Update documentation' with a due date of next Friday"

管理任务

"Show me all tasks in the Development list"

"Get details for task abc123"

"Get task CUSTOM-123"

"Update task xyz789 to mark it as complete"

"Update task PROJ-456 to change its status to In Progress"

"Change the priority of task abc123 to urgent"

"Find all tasks assigned to me that are overdue"

使用自定义 ID

自定义 ID 是特定于工作区的标识符（例如 CUSTOM-123、PROJ-456），可用于替代 ClickUp 的内部任务 ID：

"Get the task with custom ID CUSTOM-123"

"Update PROJ-456 and change the status to Complete"

"Show me the details of task MARKETING-789"

团队协作

"Who has access to task abc123?"

"Show me all members of the Development list"

开发

项目结构

clickup-mcp/
├── src/
│   ├── index.ts              # Entry point with STDIO transport
│   ├── server.ts             # MCP server setup and tool registration
│   ├── types/
│   │   └── clickup.ts        # ClickUp API type definitions
│   ├── utils/
│   │   ├── clickup-client.ts # ClickUp API wrapper
│   │   └── error-handler.ts  # Error handling utilities
│   └── tools/
│       ├── navigation.ts     # Navigation tools
│       └── tasks.ts          # Task management tools
├── dist/                     # Compiled JavaScript (generated)
├── .env                      # Environment variables (not committed)
├── .env.example              # Environment template
├── package.json              # Dependencies and scripts
├── tsconfig.json             # TypeScript configuration
└── README.md                 # This file

可用脚本

• npm run build - 将 TypeScript 编译为 JavaScript
• npm run watch - 开发用监视模式
• npm run dev - 在本地构建并运行服务

添加新工具

1. 将工具实现添加到 src/tools/ 中相应的文件
2. 使用 server.registerTool() 在工具文件中注册工具
3. 如有需要，更新 src/types/clickup.ts 中的类型定义
4. 在 src/utils/clickup-client.ts 中添加新的 API 客户端方法
5. 使用 npm run build 重新构建

故障排除

身份验证错误

如果遇到身份验证错误：

• 确认 API 令牌正确，且以 pk_ 开头
• 检查令牌是否已正确设置在 .env 文件或 Claude Desktop 配置中
• 确认令牌未在 ClickUp Settings 中被撤销

连接问题

如果 Claude Desktop 无法连接到服务：

• 确认 claude_desktop_config.json 中的路径正确
• 确认服务已成功构建（npm run build）
• 查看 Claude Desktop 日志，检查是否有错误
• 修改配置后重启 Claude Desktop

速率限制

ClickUp API 有速率限制。如果触发限制：

• 等待片刻后再发起更多请求
• 服务会提供清晰的速率限制错误消息

API 参考

如需了解 ClickUp API 的详细信息，请参阅：

• ClickUp API 文档
• ClickUp API 身份验证

许可证

MIT

贡献者

贡献者	角色
ChrisNoronha	作者与维护者
Claude Code (Anthropic)	AI 协作者 — 协助完成设计、实现和文档编写

参与贡献

欢迎参与贡献！欢迎提交问题或拉取请求。