Clickup Multi MCP Server

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

可用配置选项：

🔒 安全功能

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

快速安全设置：

# 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集成：

1. 启动启用SSE的clickup mcp服务器
2. 在n8n中，添加一个新的“MCP AI工具”节点
3. 使用以下配置节点：

- 运输：苏格兰和南方能源公司 - 服务器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个非文档）

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

会员管理工具

创建或更新任务时，您可以使用 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
}

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

鼓励

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

错误处理

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

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

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

许可证


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