使用说明

ClickUp Multi-Workspace MCP Server

A Model Context Protocol (MCP) server for integrating multiple ClickUp workspaces with AI applications. This server allows AI agents to interact with tasks, spaces, lists, and folders across different ClickUp workspaces through a standardized protocol.

🎯 主要功能：多工作区支持

此MCP服务器支持同时管理多个ClickUp工作区，使您能够：

与多个ClickUp帐户/团队合作
在工作空间之间无缝切换
为每个工作区维护单独的配置
与单一工作区设置完全向后兼容

由Alanse股份有限公司开发和维护。

需求

Node.js v18.0.0或更高版本 （MCP SDK兼容性所需）
单击要集成的每个工作区的API密钥和团队ID

快速开始

Claude代码CLI设置

将此MCP服务器添加到Claude Code的最简单方法：

单个工作区：

claude mcp add clickup \
  -e CLICKUP_API_KEY=your_api_key_here \
  -e CLICKUP_TEAM_ID=your_team_id_here \
  -- npx -y @alanse/clickup-multi-mcp-server@latest

多个工作区：

claude mcp add clickup \
  -e CLICKUP_WORKSPACES='{"default":"work","workspaces":{"work":{"token":"pk_xxx_work","teamId":"123456"},"personal":{"token":"pk_xxx_personal","teamId":"789012"}}}' \
  -- npx -y @alanse/clickup-multi-mcp-server@latest

手动配置

单工作区（向后兼容）

传统的单一工作区设置仍然与以前完全一样：

{
  "mcpServers": {
    "ClickUp": {
      "command": "npx",
      "args": ["-y", "@alanse/clickup-multi-mcp-server@latest"],
      "env": {
        "CLICKUP_API_KEY": "your-api-key",
        "CLICKUP_TEAM_ID": "your-team-id"
      }
    }
  }
}

多工作区（新功能）

使用配置多个工作区 CLICKUP_WORKSPACES 环境变量。

步骤1：创建工作区配置

创建一个JSON结构，如下所示：

{
  "default": "work",
  "workspaces": {
    "work": {
      "token": "pk_xxx_work",
      "teamId": "123456",
      "description": "Work workspace"
    },
    "personal": {
      "token": "pk_xxx_personal",
      "teamId": "789012",
      "description": "Personal projects"
    }
  }
}

步骤2：在MCP设置中使用

您可以以更易读的多行格式指定配置：

{
  "mcpServers": {
    "ClickUp": {
      "command": "npx",
      "args": ["-y", "@alanse/clickup-multi-mcp-server@latest"],
      "env": {
        // Multi-line format (most readable)
        "CLICKUP_WORKSPACES": {
          "default": "work",
          "workspaces": {
            "work": {
              "token": "pk_xxx_work",
              "teamId": "123456",
              "description": "Work workspace"
            },
            "personal": {
              "token": "pk_xxx_personal",
              "teamId": "789012",
              "description": "Personal projects"
            }
          }
        }
      }
    }
  }
}

或者作为JSON字符串（如果您的MCP客户端需要字符串格式）：

{
  "mcpServers": {
    "ClickUp": {
      "command": "npx",
      "args": ["-y", "@alanse/clickup-multi-mcp-server@latest"],
      "env": {
        "CLICKUP_WORKSPACES": "{\"default\":\"work\",\"workspaces\":{\"work\":{\"token\":\"pk_xxx_work\",\"teamId\":\"123456\"},\"personal\":{\"token\":\"pk_xxx_personal\",\"teamId\":\"789012\"}}}"
      }
    }
  }
}

💡 提示： 使用在线JSON压缩程序，然后转义引号，或使用脚本生成转义字符串：

const config = {
  default: "work",
  workspaces: {
    work: { token: "pk_xxx_work", teamId: "123456", description: "Work workspace" },
    personal: { token: "pk_xxx_personal", teamId: "789012", description: "Personal projects" }
  }
};
console.log(JSON.stringify(config));
// Copy the output and use it as CLICKUP_WORKSPACES value

使用工作空间参数

所有工具现在都支持可选 workspace 参数：

// Get tasks from default workspace
await getTasks({ list_id: "123456789" });

// Get tasks from specific workspace
await getTasks({ workspace: "personal", list_id: "987654321" });

// Get workspace hierarchy for a specific workspace
await getWorkspaceHierarchy({ workspace: "work" });

地方发展设置

对于本地开发或直接从源代码运行服务器时：

1.克隆和安装

git clone https://github.com/alanse-inc/clickup-multi-mcp-server.git
cd clickup-multi-mcp-server
npm install

2.配置环境变量

复制 .env.example 到 .env 并配置您的ClickUp凭据：

cp .env.example .env

编辑 .env 文件：

# Multi-workspace configuration
CLICKUP_WORKSPACES={"default":"alanse","workspaces":{"alanse":{"token":"pk_YOUR_TOKEN_1","teamId":"YOUR_TEAM_ID_1","description":"Alanse workspace"},"potz":{"token":"pk_YOUR_TOKEN_2","teamId":"YOUR_TEAM_ID_2","description":"Potz workspace"}}}

# Or use single workspace (legacy)
# CLICKUP_API_KEY=your_api_key_here
# CLICKUP_TEAM_ID=your_team_id_here

备注：The .env 服务器启动时，文件会自动加载。环境变量 .env 自动拾取，无需通过命令行传递。

3.构建和运行

# Build the project
npm run build

# Run locally
node build/index.js

4.配置Claude代码进行本地开发

如果你想使用Claude Code的本地版本，请更新 ~/.claude.json:

{
  "mcpServers": {
    "clickup": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/clickup-multi-mcp-server/build/index.js"]
    }
  }
}

重要：使用Claude Code进行本地构建时：

环境变量从以下位置加载 .env 项目根目录中的文件
无需指定 env 在 ~/.claude.json （除非你想覆盖 .env 值）
更改后重建： npm run build

NPM安装

此包在npm上可用 @alanse/clickup-multi-mcp-server.

将此条目添加到客户端的MCP设置JSON文件中：

{
  "mcpServers": {
    "ClickUp": {
      "command": "npx",
      "args": [
        "-y",
        "@alanse/clickup-multi-mcp-server@latest"
      ],
      "env": {
        "CLICKUP_API_KEY": "your-api-key",
        "CLICKUP_TEAM_ID": "your-team-id",
        "DOCUMENT_SUPPORT": "true"
      }
    }
  }
}

或者使用以下npx命令：

npx -y @alanse/clickup-multi-mcp-server@latest --env CLICKUP_API_KEY=your-api-key --env CLICKUP_TEAM_ID=your-team-id

Obs：如果您没有传递“DOCUMENT_SUPPORT”：“true”，则默认值为false，文档支持将不会处于活动状态。

工具筛选

您可以使用两个互补的环境变量来控制哪些工具可用：

启用_工具（推荐）

使用 ENABLED_TOOLS 要准确指定应提供哪些工具：

# Environment variable
export ENABLED_TOOLS="create_task,get_task,update_task,get_workspace_hierarchy"

# Command line argument
--env ENABLED_TOOLS=create_task,get_task,update_task,get_workspace_hierarchy

禁用_工具（旧版）

使用 DISABLED_TOOLS 禁用特定工具，同时保持所有其他工具启用：

# Environment variable
export DISABLED_TOOLS="delete_task,delete_bulk_tasks"

# Command line argument
--env DISABLED_TOOLS=delete_task,delete_bulk_tasks

优先规则

如果 ENABLED_TOOLS 如果指定了，则只有这些工具可用（优先于 DISABLED_TOOLS)
要是…就好了 DISABLED_TOOLS 指定后，除列出的工具外，所有工具都将可用
如果两者都没有指定，则所有工具都可用（默认行为）

例子：

# Only enable task creation and reading tools
npx -y @alanse/clickup-multi-mcp-server@latest \
  --env CLICKUP_API_KEY=your-api-key \
  --env CLICKUP_TEAM_ID=your-team-id \
  --env ENABLED_TOOLS=create_task,get_task,get_workspace_hierarchy

如果您在工具数量或任何上下文限制方面有问题，请过滤您不需要的工具。

使用HTTP传输支持运行

服务器支持现代 HTTP流式传输 传输（兼容MCP检查器）和传统 SSE（服务器发送事件） 传输以实现向后兼容性。

{
  "mcpServers": {
    "ClickUp": {
      "command": "npx",
      "args": [
        "-y",
        "@alanse/clickup-multi-mcp-server@latest"
      ],
      "env": {
        "CLICKUP_API_KEY": "your-api-key",
        "CLICKUP_TEAM_ID": "your-team-id",
        "ENABLE_SSE": "true",
        "PORT": "3231"
      }
    }
  }
}

终点：

主要的，重要的: http://127.0.0.1:3231/mcp （流式HTTP）
遗产: http://127.0.0.1:3231/sse （SSE用于向后兼容性）

命令行用法

npx -y @alanse/clickup-multi-mcp-server@latest --env CLICKUP_API_KEY=your-api-key --env CLICKUP_TEAM_ID=your-team-id --env ENABLE_SSE=true --env PORT=3231

可用配置选项：

选项	描述	默认值
`ENABLED_TOOLS`	以逗号分隔的要启用的工具列表（优先）	所有工具
`DISABLED_TOOLS`	以逗号分隔的禁用工具列表	无
`ENABLE_SSE`	启用HTTP/SSE传输	`false`
`PORT`	HTTP服务器的端口	`3231`
`ENABLE_STDIO`	启用STDIO传输	`true`
`ENABLE_SECURITY_FEATURES`	启用安全标头和日志记录	`false`
`ENABLE_HTTPS`	启用HTTPS/TLS加密	`false`
`ENABLE_ORIGIN_VALIDATION`	根据白名单验证Origin标头	`false`
`ENABLE_RATE_LIMIT`	启用速率限制保护	`false`

🔒 安全功能

该服务器包括用于生产部署的可选安全增强功能。所有安全功能都是 选择加入 和 默认情况下禁用 以保持向后兼容性。

快速安全设置：

# Generate SSL certificates for HTTPS
./scripts/generate-ssl-cert.sh

# Start with full security
ENABLE_SECURITY_FEATURES=true \
ENABLE_HTTPS=true \
ENABLE_ORIGIN_VALIDATION=true \
ENABLE_RATE_LIMIT=true \
SSL_KEY_PATH=./ssl/server.key \
SSL_CERT_PATH=./ssl/server.crt \
npx @alanse/clickup-multi-mcp-server@latest --env CLICKUP_API_KEY=your-key --env CLICKUP_TEAM_ID=your-team --env ENABLE_SSE=true

HTTPS端点：

主要的，重要的: https://127.0.0.1:3443/mcp （可流式传输HTTPS）
遗产: https://127.0.0.1:3443/sse （SSE HTTPS向后兼容）
健康: https://127.0.0.1:3443/health （健康检查）

有关详细的安全配置，请参阅安全功能文档.

n8n集成

要与n8n集成：

启动启用SSE的clickup mcp服务器
在n8n中，添加一个新的“MCP AI工具”节点
使用以下配置节点：
- 运输：苏格兰和南方能源公司
- 服务器URL: http://localhost:3231 （或您的服务器地址）
- 工具：选择要使用的ClickUp工具

客户端示例

SSE客户端示例见 examples 目录。要运行它：

# Start the server with SSE enabled
ENABLE_SSE=true PORT=3231 npx -y @alanse/clickup-multi-mcp-server@latest --env CLICKUP_API_KEY=your-api-key --env CLICKUP_TEAM_ID=your-team-id

# In another terminal, run the example client
cd examples
npm install
npm run sse-client

特性

📝 任务管理	🏷️ 标签管理
•创建、更新和删除任务 •在任何地方移动和复制任务 •支持单次和批量操作 •用自然语言设置开始/截止日期 •创建和管理子任务 •添加评论和附件	•创建、更新和删除空间标签 •在任务中添加和删除标签 •使用自然语言颜色命令 •自动对比前景颜色 •查看所有空间标签 •跨工作区的基于标签的任务组织
⏱️ 时间追踪	🌳 工作区组织
•查看任务的时间条目 •任务的开始/停止时间跟踪 •添加手动时间输入 •删除时间条目 •查看当前运行的计时器 •跟踪计费和非计费时间	•浏览空间、文件夹和列表 •创建和管理文件夹 •在空间内组织列表 •在文件夹中创建列表 •查看工作空间层次结构 •高效的路径导航
📄 文档管理	👥 会员管理
•通过所有工作区列出文档 •文档页面列表 •文档页面详细信息 •文档创建 •文档页面更新（追加和预置）	•通过姓名或电子邮件查找工作区成员 •确定任务的指定人员 •查看成员详细信息和权限 •在创建和更新过程中为用户分配任务 •支持用户ID、电子邮件或用户名 •全团队用户管理
👁️ 视图管理
•创建和管理所有层次结构级别（工作区、空间、文件夹、列表）的视图 •支持列表、板、日历、表格、甘特图、时间线、工作量等 •更新视图分组、排序和筛选设置 •删除视图 •检索特定视图中的任务（带分页）
⚡ 集成功能	🏗️ 架构与性能
•基于全局名称或ID的查找 •不区分大小写的匹配 •Markdown格式支持 •内置速率限制 •错误处理和验证 •全面的API覆盖范围	• 代码库减少70% 为了提高性能 • 统一架构跨越所有运输类型 • 零代码重复 • HTTP流式传输（MCP检查员兼容） • 传统SSE支持为了向后兼容性

可用工具（共81个，74个非文档）

工具	说明	必需参数
get_works空间层次结构	获取工作区结构	无
get_available_workspaces	获取所有可用工作区	无
创建任务	创建任务	`name`, (`listId`/`listName`)
create_bulk_tasks	创建多个任务	`tasks[]`
update_task	修改任务	`taskId`/`taskName`
update_bulk_tasks	更新多个任务	`tasks[]` 带有ID或名称
get_tasks	从列表中获取任务	`listId`/`listName`
获取任务	获取单任务详细信息	`taskId`/`taskName` （巧妙地消除歧义）
get_workspace_tasks	使用筛选获取任务	至少一个筛选器（标签、list_ids、空格_ids等）
get_ask_comments	获取任务的评论	`taskId`/`taskName`
创建任务注释	向任务添加注释	`commentText`, (`taskId`/(`taskName`+`listName`))
附件任务文件	将文件附加到任务	`taskId`/`taskName`, (`file_data` 或 `file_url`)
删除任务	删除任务	`taskId`/`taskName`
delete_bulk_tasks	删除多个任务	`tasks[]` 带有ID或名称
移动任务	移动任务	`taskId`/`taskName`, `listId`/`listName`
move_bulk_tasks	移动多个任务	`tasks[]` 带有ID或名称的目标列表
重复任务	复制任务	`taskId`/`taskName`, `listId`/`listName`
合并任务	合并两个任务	`taskId`, `mergeFromId`
get_task_time_in_status	获取任务的时间状态	`taskId`/`taskName`
get_bulk_tasks_time_in_status	获取批量时间状态	`taskIds[]`
add_task_to_list	将任务添加到其他列表	`listId`, `taskId`
remove_task_from_list	从列表中删除任务	`listId`, `taskId`
create_list	在空间中创建列表	`name`, `spaceId`/`spaceName`
创建文件夹	创建文件夹	`name`, `spaceId`/`spaceName`
create_list_in_folder	在文件夹中创建列表	`name`, `folderId`/`folderName`
获取文件夹	获取文件夹详细信息	`folderId`/`folderName`
update_folder	更新文件夹属性	`folderId`/`folderName`
删除文件夹	删除文件夹	`folderId`/`folderName`
get_list	获取列表详细信息	`listId`/`listName`
update_list	更新列表属性	`listId`/`listName`
delete_list	删除列表	`listId`/`listName`
get_space_tags	获取空间标签	`spaceId`/`spaceName`
create_space_tag	创建标签	`tagName`, `spaceId`/`spaceName`
update_space_tag	更新标签	`tagName`, `spaceId`/`spaceName`
delete_space_tag	删除标签	`tagName`, `spaceId`/`spaceName`
add_tag_to_totask	向任务添加标签	`tagName`, `taskId`/(`taskName`+`listName`)
remove_tag_from_task	从任务中删除标记	`tagName`, `taskId`/(`taskName`+`listName`)
get_task_time_entrys	获取任务的时间条目	`taskId`/`taskName`
开始时间跟踪	任务的开始时间跟踪	`taskId`/`taskName`
停止时间跟踪	停止当前时间跟踪	无
add_time_entry	向任务添加手动时间输入	`taskId`/`taskName`, `start`, `duration`
delete_time_entry	删除时间条目	`timeEntryId`
get_current_time_entry	获取当前正在运行的计时器	无
get_workspace_members	获取所有工作区成员	无
find_member_by_name	通过姓名或电子邮件查找成员	`nameOrEmail`
解决方案_受让人	将成员名称解析为ID	`assignees[]`
创建_文档	创建文档	`workspaceId`, `name`, `parentId`/`parentType`, `visibility`, `create_pages`
get_document	获取文档	`workspaceId`/`documentId`
list_文档	列出文件	`workspaceId`, `documentId`/`creator`/`deleted`/`archived`/`parent_id`/`parent_type`/`limit`/`next_cursor`
list_document_pages	列出文档页面	`documentId`/`documentName`
get_document_pages	获取文档页面	`documentId`/`documentName`, `pageIds`
create_document_pages	创建文档页面	`workspaceId`/`documentId`, `parent_page_id`/`name`/`sub_title`,`content`/`content_format`
update_document_page	更新文档页面	`workspaceId`/`documentId`, `name`/`sub_title`,`content`/`content_edit_mode`/`content_format`

看全部文件用于可选参数和高级用法。

会员管理工具

创建或更新任务时，您可以使用 assignees 参数。该参数接受用户ID、电子邮件或用户名的数组：

与指定人员一起创建任务：

{
  "name": "New Task",
  "description": "This is a new task.",
  "assignees": ["jdoe@example.com", "Jane Smith"]  // Emails, usernames, or user IDs
}

更新任务分配者：

{
  "taskId": "abc123",
  "assignees": ["newuser@example.com"]  // Replace existing assignees
}

成员管理工具可在需要时帮助解析用户引用。

鼓励

尚未实现，并非所有客户端应用程序都支持。请求一个对您的工作流程最有利的快速实现功能（不要太具体）。示例：

提示	目的	功能
总结任务	任务概述	状态摘要、优先级、关系
分析优先级	优先级优化	分布分析、排序
generate-description	任务描述创建	目标、标准、依赖关系

错误处理

服务器为以下对象提供明确的错误消息：

缺少必要参数
ID或名称无效
未找到项目
权限问题
API错误
速率限制

这 LOG_LEVEL 可以指定环境变量来控制服务器日志的详细程度。有效值为 trace, debug, info, warn，以及 error （默认）。这也可以在命令行上指定，例如。 --env LOG_LEVEL=info.

许可证

此项目根据MIT许可证获得许可-请参阅许可证文件以获取详细信息。