![\"ClickUp](\"assets/images/clickup-social.png\")
\n\n \n
\n 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.\n
\n\n## 🎯 Key Feature: Multi-Workspace Support\n\nThis MCP server supports managing multiple ClickUp workspaces simultaneously, allowing you to:\n- Work with multiple ClickUp accounts/teams\n- Switch between workspaces seamlessly\n- Maintain separate configurations for each workspace\n- Full backwards compatibility with single workspace setup\n\nDeveloped and maintained by Alanse Inc.\n\n## Requirements\n\n- **Node.js v18.0.0 or higher** (required for MCP SDK compatibility)\n- ClickUp API key and Team ID for each workspace you want to integrate\n\n## Quick Start\n\n### Claude Code CLI Setup\n\nThe easiest way to add this MCP server to Claude Code:\n\n**Single Workspace:**\n```bash\nclaude mcp add clickup \\\n -e CLICKUP_API_KEY=your_api_key_here \\\n -e CLICKUP_TEAM_ID=your_team_id_here \\\n -- npx -y @alanse/clickup-multi-mcp-server@latest\n```\n\n**Multiple Workspaces:**\n```bash\nclaude mcp add clickup \\\n -e CLICKUP_WORKSPACES='{\"default\":\"work\",\"workspaces\":{\"work\":{\"token\":\"pk_xxx_work\",\"teamId\":\"123456\"},\"personal\":{\"token\":\"pk_xxx_personal\",\"teamId\":\"789012\"}}}' \\\n -- npx -y @alanse/clickup-multi-mcp-server@latest\n```\n\n### Manual Configuration\n\n### Single Workspace (Backwards Compatible)\n\nThe traditional single workspace setup still works exactly as before:\n\n```json\n{\n \"mcpServers\": {\n \"ClickUp\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@alanse/clickup-multi-mcp-server@latest\"],\n \"env\": {\n \"CLICKUP_API_KEY\": \"your-api-key\",\n \"CLICKUP_TEAM_ID\": \"your-team-id\"\n }\n }\n }\n}\n```\n\n### Multiple Workspaces (New Feature)\n\nConfigure multiple workspaces using the `CLICKUP_WORKSPACES` environment variable.\n\n**Step 1: Create your workspace configuration**\n\nCreate a JSON structure like this:\n\n```json\n{\n \"default\": \"work\",\n \"workspaces\": {\n \"work\": {\n \"token\": \"pk_xxx_work\",\n \"teamId\": \"123456\",\n \"description\": \"Work workspace\"\n },\n \"personal\": {\n \"token\": \"pk_xxx_personal\",\n \"teamId\": \"789012\",\n \"description\": \"Personal projects\"\n }\n }\n}\n```\n\n**Step 2: Use in your MCP settings**\n\nYou can specify the configuration in a more readable multi-line format:\n\n```jsonc\n{\n \"mcpServers\": {\n \"ClickUp\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@alanse/clickup-multi-mcp-server@latest\"],\n \"env\": {\n // Multi-line format (most readable)\n \"CLICKUP_WORKSPACES\": {\n \"default\": \"work\",\n \"workspaces\": {\n \"work\": {\n \"token\": \"pk_xxx_work\",\n \"teamId\": \"123456\",\n \"description\": \"Work workspace\"\n },\n \"personal\": {\n \"token\": \"pk_xxx_personal\",\n \"teamId\": \"789012\",\n \"description\": \"Personal projects\"\n }\n }\n }\n }\n }\n }\n}\n```\n\nOr as a JSON string (if your MCP client requires string format):\n\n```json\n{\n \"mcpServers\": {\n \"ClickUp\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@alanse/clickup-multi-mcp-server@latest\"],\n \"env\": {\n \"CLICKUP_WORKSPACES\": \"{\\\"default\\\":\\\"work\\\",\\\"workspaces\\\":{\\\"work\\\":{\\\"token\\\":\\\"pk_xxx_work\\\",\\\"teamId\\\":\\\"123456\\\"},\\\"personal\\\":{\\\"token\\\":\\\"pk_xxx_personal\\\",\\\"teamId\\\":\\\"789012\\\"}}}\"\n }\n }\n }\n}\n```\n\n**💡 Tip:** Use an online JSON minifier and then escape the quotes, or use a script to generate the escaped string:\n\n```javascript\nconst config = {\n default: \"work\",\n workspaces: {\n work: { token: \"pk_xxx_work\", teamId: \"123456\", description: \"Work workspace\" },\n personal: { token: \"pk_xxx_personal\", teamId: \"789012\", description: \"Personal projects\" }\n }\n};\nconsole.log(JSON.stringify(config));\n// Copy the output and use it as CLICKUP_WORKSPACES value\n```\n\n### Using Workspace Parameter\n\nAll tools now support an optional `workspace` parameter:\n\n```typescript\n// Get tasks from default workspace\nawait getTasks({ list_id: \"123456789\" });\n\n// Get tasks from specific workspace\nawait getTasks({ workspace: \"personal\", list_id: \"987654321\" });\n\n// Get workspace hierarchy for a specific workspace\nawait getWorkspaceHierarchy({ workspace: \"work\" });\n```\n\n## Local Development Setup\n\nFor local development or when running the server directly from source code:\n\n### 1. Clone and Install\n\n```bash\ngit clone https://github.com/alanse-inc/clickup-multi-mcp-server.git\ncd clickup-multi-mcp-server\nnpm install\n```\n\n### 2. Configure Environment Variables\n\nCopy `.env.example` to `.env` and configure your ClickUp credentials:\n\n```bash\ncp .env.example .env\n```\n\nEdit `.env` file:\n\n```bash\n# Multi-workspace configuration\nCLICKUP_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\"}}}\n\n# Or use single workspace (legacy)\n# CLICKUP_API_KEY=your_api_key_here\n# CLICKUP_TEAM_ID=your_team_id_here\n```\n\n**Note**: The `.env` file is automatically loaded when the server starts. Environment variables in `.env` are automatically picked up without needing to pass them via command line.\n\n### 3. Build and Run\n\n```bash\n# Build the project\nnpm run build\n\n# Run locally\nnode build/index.js\n```\n\n### 4. Configure Claude Code for Local Development\n\nIf you want to use your local build with Claude Code, update `~/.claude.json`:\n\n```json\n{\n \"mcpServers\": {\n \"clickup\": {\n \"type\": \"stdio\",\n \"command\": \"node\",\n \"args\": [\"/absolute/path/to/clickup-multi-mcp-server/build/index.js\"]\n }\n }\n}\n```\n\n**Important**: When using local build with Claude Code:\n- Environment variables are loaded from `.env` file in the project root\n- No need to specify `env` in `~/.claude.json` (unless you want to override `.env` values)\n- Rebuild after making changes: `npm run build`\n\n## NPM Installation\n\nThis package is available on npm as `@alanse/clickup-multi-mcp-server`.\n\nAdd this entry to your client's MCP settings JSON file:\n\n```json\n{\n \"mcpServers\": {\n \"ClickUp\": {\n \"command\": \"npx\",\n \"args\": [\n \"-y\",\n \"@alanse/clickup-multi-mcp-server@latest\"\n ],\n \"env\": {\n \"CLICKUP_API_KEY\": \"your-api-key\",\n \"CLICKUP_TEAM_ID\": \"your-team-id\",\n \"DOCUMENT_SUPPORT\": \"true\"\n }\n }\n }\n}\n```\n\nOr use this npx command:\n\n`npx -y @alanse/clickup-multi-mcp-server@latest --env CLICKUP_API_KEY=your-api-key --env CLICKUP_TEAM_ID=your-team-id`\n\n**Obs: if you don't pass \"DOCUMENT_SUPPORT\": \"true\", the default is false and document support will not be active.**\n\n### Tool Filtering\n\nYou can control which tools are available using two complementary environment variables:\n\n#### ENABLED_TOOLS (Recommended)\nUse `ENABLED_TOOLS` to specify exactly which tools should be available:\n```bash\n# Environment variable\nexport ENABLED_TOOLS=\"create_task,get_task,update_task,get_workspace_hierarchy\"\n\n# Command line argument\n--env ENABLED_TOOLS=create_task,get_task,update_task,get_workspace_hierarchy\n```\n\n#### DISABLED_TOOLS (Legacy)\nUse `DISABLED_TOOLS` to disable specific tools while keeping all others enabled:\n```bash\n# Environment variable\nexport DISABLED_TOOLS=\"delete_task,delete_bulk_tasks\"\n\n# Command line argument\n--env DISABLED_TOOLS=delete_task,delete_bulk_tasks\n```\n\n#### Precedence Rules\n- If `ENABLED_TOOLS` is specified, only those tools will be available (takes precedence over `DISABLED_TOOLS`)\n- If only `DISABLED_TOOLS` is specified, all tools except those listed will be available\n- If neither is specified, all tools are available (default behavior)\n\n**Example:**\n```bash\n# Only enable task creation and reading tools\nnpx -y @alanse/clickup-multi-mcp-server@latest \\\n --env CLICKUP_API_KEY=your-api-key \\\n --env CLICKUP_TEAM_ID=your-team-id \\\n --env ENABLED_TOOLS=create_task,get_task,get_workspace_hierarchy\n```\n\nPlease filter tools you don't need if you are having issues with the number of tools or any context limitations.\n\n## Running with HTTP Transport Support\n\nThe server supports both modern **HTTP Streamable** transport (MCP Inspector compatible) and legacy **SSE (Server-Sent Events)** transport for backwards compatibility.\n\n```json\n{\n \"mcpServers\": {\n \"ClickUp\": {\n \"command\": \"npx\",\n \"args\": [\n \"-y\",\n \"@alanse/clickup-multi-mcp-server@latest\"\n ],\n \"env\": {\n \"CLICKUP_API_KEY\": \"your-api-key\",\n \"CLICKUP_TEAM_ID\": \"your-team-id\",\n \"ENABLE_SSE\": \"true\",\n \"PORT\": \"3231\"\n }\n }\n }\n}\n```\n\n**Endpoints:**\n- **Primary**: `http://127.0.0.1:3231/mcp` (Streamable HTTP)\n- **Legacy**: `http://127.0.0.1:3231/sse` (SSE for backwards compatibility)\n\n### Command Line Usage\n\n```bash\nnpx -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\n```\n\nAvailable configuration options:\n\n| Option | Description | Default |\n| ------ | ----------- | ------- |\n| `ENABLED_TOOLS` | Comma-separated list of tools to enable (takes precedence) | All tools |\n| `DISABLED_TOOLS` | Comma-separated list of tools to disable | None |\n| `ENABLE_SSE` | Enable the HTTP/SSE transport | `false` |\n| `PORT` | Port for the HTTP server | `3231` |\n| `ENABLE_STDIO` | Enable the STDIO transport | `true` |\n| `ENABLE_SECURITY_FEATURES` | Enable security headers and logging | `false` |\n| `ENABLE_HTTPS` | Enable HTTPS/TLS encryption | `false` |\n| `ENABLE_ORIGIN_VALIDATION` | Validate Origin header against whitelist | `false` |\n| `ENABLE_RATE_LIMIT` | Enable rate limiting protection | `false` |\n\n### 🔒 Security Features\n\nThe server includes optional security enhancements for production deployments. All security features are **opt-in** and **disabled by default** to maintain backwards compatibility.\n\n**Quick security setup:**\n```bash\n# Generate SSL certificates for HTTPS\n./scripts/generate-ssl-cert.sh\n\n# Start with full security\nENABLE_SECURITY_FEATURES=true \\\nENABLE_HTTPS=true \\\nENABLE_ORIGIN_VALIDATION=true \\\nENABLE_RATE_LIMIT=true \\\nSSL_KEY_PATH=./ssl/server.key \\\nSSL_CERT_PATH=./ssl/server.crt \\\nnpx @alanse/clickup-multi-mcp-server@latest --env CLICKUP_API_KEY=your-key --env CLICKUP_TEAM_ID=your-team --env ENABLE_SSE=true\n```\n\n**HTTPS Endpoints:**\n- **Primary**: `https://127.0.0.1:3443/mcp` (Streamable HTTPS)\n- **Legacy**: `https://127.0.0.1:3443/sse` (SSE HTTPS for backwards compatibility)\n- **Health**: `https://127.0.0.1:3443/health` (Health check)\n\nFor detailed security configuration, see [Security Features Documentation](docs/security-features.md).\n\n#### n8n Integration\n\nTo integrate with n8n:\n\n1. Start the clickup-mcp-server with SSE enabled\n2. In n8n, add a new \"MCP AI Tool\" node\n3. Configure the node with:\n - Transport: SSE\n - Server URL: `http://localhost:3231` (or your server address)\n - Tools: Select the ClickUp tools you want to use\n\n#### Example Client\n\nAn example SSE client is provided in the `examples` directory. To run it:\n\n```bash\n# Start the server with SSE enabled\nENABLE_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\n\n# In another terminal, run the example client\ncd examples\nnpm install\nnpm run sse-client\n```\n\n## Features\n\n| 📝 Task Management | 🏷️ Tag Management |\n| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| • Create, update, and delete tasks![\"GitHub](\"https://img.shields.io/github/stars/alanse-inc/clickup-multi-mcp-server?style=flat&logo=github\")
\n ![\"NPM](\"https://img.shields.io/npm/v/@alanse/clickup-multi-mcp-server.svg?style=flat&logo=npm\")
\n