ClickUp MCP Server — Premium

ClickUp MCP Server Premium Logo

--- **Properly Connect ClickUp to AI Agents and Agentic Workflows** _A high-performance Model Context Protocol (MCP) server for managing tasks, checklists, sprints, comments, tags, spaces, lists, folders, files, docs, chat, and time using natural language._ **⭐️ Proven Performance:** 460+ Stars (from previous public repo) & thousands of weekly NPM downloads. The industry-standard ClickUp integration for AI. --- ## 📚 Table of Contents | Links | Quick Start & Installation | | :--- | :--- | | • [Features](#features)
• [Premium Access](#premium-access)
• [Available Tools](#available-tools)
• [Adv. Config](#advanced-configuration)
• [FAQ](#faq)
• [Disclaimer](#disclaimer) |

[ Antigravity](#antigravity-setup)	[ Agy CLI](#antigravity-cli-setup)	[ Hermes](#hermes-setup)	[ OpenClaw](#openclaw-setup)
[ Cursor](#cursor-setup)	[ VS Code](#vscode-setup)	[ Claude](#claude-desktop-setup)	[ ClaudeCode](#claude-code-setup)
[ n8n](#n8n-setup)	[ Codex](#codex-setup)	[ ChatGPT](#chatgpt-setup)	[ Augment](#augment-setup)
[ Auggie](#auggierun-setup)	[ Windsurf](#windsurf-setup)	[ Roo Code](#roocode-setup)	[➕ Add Agent](mailto:info@taazkareem.com?subject=Redirect%20URI%20Whitelist%20Request)

| --- ## ✨ Features **🔥 Multi-Account Support:** Manage multiple authorized workspaces seamlessly in a single session. [See setup](#multi-workspace-support)

🔐 Hybrid Authentication MCP spec-compliant OAuth 2.1 with advanced security hardening and session-isolated caching for fast, secure multi-tenant operation. Backwards compatible with API Key/Team ID(s).	🔍 Intelligent Search & Resolution Smart tiered, global fuzzy search across task, list, folder, and space names, custom fields, members/emails, statuses, tags, descriptions, and more. Automatic resolution—no IDs needed.
📝 Task Management Full CRUD, move, duplicate, link, and set dependencies between tasks. Supports bulk operations, nested subtasks, checklists, sprints (active detection), natural language dates, custom task IDs, custom task types, custom fields, task templates, and file attachments (upload via URL, local path, or base64).	⏱️ Time Tracking Start/stop timers, log manual entries, edit existing entries, retrieve timer history, manage time entry tags, and filter time entries across the entire workspace using natural language dates or date ranges.
📄 Document Management Create, read, and append to ClickUp Docs with full markdown text. Manage pages within documents for structured, long-form content (consolidated action-based tool).	💬 Comments & Chat Post, edit, resolve, and reply to comments on tasks, lists, and views. Create and manage chat channels (including DMs), send messages with threaded replies, reactions, and follower management. Both support rich text, subtypes, and @mentions.
🎯 Goals & Key Results Create and manage Goals with full lifecycle support—create, update, delete, and archive. Define and track nested Key Results to measure OKR progress across the workspace.	📋 Views Create, list, update, and delete views at any level of the workspace hierarchy—space, folder, or list. Fetch tasks scoped to a specific view for focused filtering.
🗂️ Task Templates Browse available task templates and instantly create tasks from them. Streamlines repeatable workflows without manual setup each time.	🌳 Workspace Control Full CRUD for spaces, folders, lists, webhooks, and tags across the entire workspace hierarchy. Manage access control (ACL) permissions at any level. Switch workspaces mid-conversation without reconfiguration.

--- ## 💎 Premium Access

Unlock 150 Enterprise-Grade Custom Tools

This project transitioned from open-source to a paid model for sustainable full-time development and priority support. A license grants full, unrestricted access to all features across your agents⎯no limits.
| [**Monthly**](https://buy.polar.sh/polar_cl_3xQojQLgzQXKCLzsxc49YfL6z8hzSBBqh9ivy1qZdwW?utm_source=github&utm_medium=readme) $9/mo | [**Annual**](https://buy.polar.sh/polar_cl_3a8a3055T4CHIoVlSQPsNshOJLUwsM8AHAiIR3y9wTZ?utm_source=github&utm_medium=readme) $59/yr | [**Lifetime**](https://buy.polar.sh/polar_cl_4ha3uVyJTu4iPZJS1QbBYNTI1MKTvaXXCkZTb45vPPF?utm_source=github&utm_medium=readme) $89 w/ code | | :--------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | • Pay-as-you-go flexibility
• 3 device activations
• Cancel anytime | • **Save 45%** ($4.92/mo)
• 3 device activations
• Priority support all year | • **Best Value** — One payment
• 3 device activations
• **25% OFF** code: `SEP25` |

**⚡️ Instant Key Delivery (Polar.sh)** • **Setup takes less than 2 mins**

--- ## 🚀 Quick Start ### 1. Prerequisites - **License Key:** See above - **ClickUp API Key** (Optional - not needed for Remote MCP) - Log into ClickUp and go to [ClickUp Settings → Apps](https://app.clickup.com/settings/apps). - Click **Generate** under "API Token" (or copy your existing one). - **ClickUp Team ID** (Optional - not needed for Remote MCP) - Open ClickUp in your browser. - Look at the URL: `https://app.clickup.com/1234567/v/li/987654321`. - The first number (`1234567`) directly after `clickup.com/` is your **Team ID** (Workspace ID). ### 2. Choose your MCP Host & Transport

Antigravity (IDE & 2.0)

Download from [antigravity.google](https://antigravity.google). Covers **Antigravity IDE** (VS Code-based agentic editor) and **Antigravity 2.0** (standalone desktop agent orchestration app). Both share the same configuration file. **Configuration Path:** `~/.gemini/config/mcp_config.json` > **Tip:** Open the Agent Panel → **...** → **Manage MCP Servers** → **View raw config** to open this file directly. Or type `/mcp` in the prompt panel. **Option A: Remote / Streamable HTTP (Recommended)** ```json { "mcpServers": { "ClickUp": { "serverUrl": "https://clickup-mcp.taazkareem.com/mcp", "headers": { "X-License-Key": "your-license-key" } } } } ``` **Option B: Local / STDIO** ```json { "mcpServers": { "ClickUp": { "command": "npx", "args": ["-y", "@taazkareem/clickup-mcp-server@latest"], "env": { "CLICKUP_API_KEY": "your-api-key", "CLICKUP_TEAM_ID": "your-team-id", "CLICKUP_MCP_LICENSE_KEY": "your-license-key" } } } } ```

Antigravity CLI (agy)

A lightweight terminal-based interface (TUI) for Antigravity agents. Install with: ```bash curl -fsSL https://antigravity.google/cli/install.sh | bash ``` **Configuration Path:** `~/.gemini/antigravity-cli/mcp_config.json` > **Tip:** Run `agy` and type `/mcp` in the interactive session to manage servers from within the TUI. **Option A: Remote / Streamable HTTP (Recommended)** ```json { "mcpServers": { "ClickUp": { "serverUrl": "https://clickup-mcp.taazkareem.com/mcp", "headers": { "X-License-Key": "your-license-key" } } } } ``` **Option B: Local / STDIO** ```json { "mcpServers": { "ClickUp": { "command": "npx", "args": ["-y", "@taazkareem/clickup-mcp-server@latest"], "env": { "CLICKUP_API_KEY": "your-api-key", "CLICKUP_TEAM_ID": "your-team-id", "CLICKUP_MCP_LICENSE_KEY": "your-license-key" } } } } ```

Hermes Agent

**Single Agent Configuration Path:** `~/.hermes/config.yaml` **Option A: Remote / Streamable HTTP** ```bash hermes mcp add clickup \ --url https://clickup-mcp.taazkareem.com/mcp \ --auth oauth && \ hermes config set mcp_servers.clickup.headers.X-License-Key "your-license-key" ``` **Option B: Local / STDIO** ```bash hermes mcp add clickup \ --command npx \ --args -y @taazkareem/clickup-mcp-server@latest \ --env CLICKUP_API_KEY="your-api-key" \ CLICKUP_TEAM_ID="your-team-id" \ CLICKUP_MCP_LICENSE_KEY="your-license-key" ``` - Run it: `hermes` --- #### Multi-Agent Setup (Profiles + Personas) Run a **team of specialized agents** on the same workspace (or separate). Each Hermes **profile** is an isolated agent with its own config and `SOUL.md` instructions. Configure each profile to match a **persona** (`X-Persona`) as needed. This will scope which ClickUp tools is in its context. **Guide with examples:** **1. Create the profiles** ```bash hermes profile create project_manager hermes profile create task_worker hermes profile create auditor ``` > Optional: Use `--clone` to copy the existing config.yaml/.env/SOUL.md, or re-run the commands from above. **2. Set each profile's persona.** The profile has the MCP config now, so just add the matching persona: ```bash project_manager config set mcp_servers.clickup.headers.X-Persona "project_manager" task_worker config set mcp_servers.clickup.headers.X-Persona "task_worker" auditor config set mcp_servers.clickup.headers.X-Persona "auditor" ``` > See [→ Advanced Configuration ](#advanced-configuration) for more customized filtering options. **3. Give each agent its instructions** in `~/.hermes/profiles//SOUL.md` (`auditor` shown): ```markdown # ClickUp Auditor You are a read-only project auditor. Observe and report — never change anything. - Summarize task status, overdue items, and blockers concisely. - Surface risks and recommend actions, but never execute them. - If asked to create or modify a task, decline and explain you are read-only. ``` **Run any agent query by its profile (call by User or Agent):** ```bash project_manager chat -q "Break the Q3 launch into a list with subtasks and owners" auditor chat -q "Audit the Sprint board and report what's at risk" ``` -OR- **Run a TUI or Gateway called by User:** ```bash project_manager gateway start auditor chat ``` --- **Other (Custom Agents, etc.)** For most other MCP-compliant hosts: - **Server URL:** `https://clickup-mcp.taazkareem.com/mcp` - **Auth Header:** `X-License-Key: your-license-key`

OpenClaw (via mcporter)

**1. Enable** mcporter in `~/.openclaw/openclaw.json`: ```json { "skills": { "allowBundled": ["mcporter"] } } ``` **2. Configure & Auth** ```bash # Add ClickUp as a remote server mcporter config add ClickUp https://clickup-mcp.taazkareem.com/mcp --auth oauth --header "X-License-Key=your-license-key" # Authenticate session mcporter auth ClickUp ``` > **Pro Tip:** Use [Personas](#advanced-configuration) to define multiple isolated configurations (e.g., Auditor vs. Worker) in your agent's `mcporter.json`.

Cursor

**Configuration Path:** `/.cursor/mcp.json` **Option A: Remote / Streamable HTTP (Easiest)** ```json { "mcpServers": { "ClickUp": { "url": "https://clickup-mcp.taazkareem.com/mcp", "headers": { "X-License-Key": "your-license-key" } } } } ``` **Option B: Local / STDIO** ```json { "mcpServers": { "ClickUp": { "command": "npx", "args": ["-y", "@taazkareem/clickup-mcp-server@latest"], "env": { "CLICKUP_API_KEY": "your-api-key", "CLICKUP_TEAM_ID": "your-team-id", "CLICKUP_MCP_LICENSE_KEY": "your-license-key" } } } } ```

VS Code

**Configuration Paths:** - **Global:** `~/Library/Application Support/Code/User/mcp.json` - **Local:** `/.vscode/mcp.json` **Option A: Remote / Streamable HTTP (Easiest)** ```json { "mcpServers": { "ClickUp": { "url": "https://clickup-mcp.taazkareem.com/mcp", "headers": { "X-License-Key": "your-license-key" } } } } ``` **Option B: Local / STDIO** ```json { "mcpServers": { "ClickUp": { "command": "npx", "args": ["-y", "@taazkareem/clickup-mcp-server@latest"], "env": { "CLICKUP_API_KEY": "your-api-key", "CLICKUP_TEAM_ID": "your-team-id", "CLICKUP_MCP_LICENSE_KEY": "your-license-key" } } } } ```

Roo Code

**Configuration Path:** `/.roo/mcp.json` **Option A: Remote / Streamable HTTP (Easiest)** ```json { "mcpServers": { "ClickUp": { "url": "https://clickup-mcp.taazkareem.com/mcp", "headers": { "X-License-Key": "your-license-key" } } } } ``` **Option B: Local / STDIO** ```json { "mcpServers": { "ClickUp": { "command": "npx", "args": ["-y", "@taazkareem/clickup-mcp-server@latest"], "env": { "CLICKUP_API_KEY": "your-api-key", "CLICKUP_TEAM_ID": "your-team-id", "CLICKUP_MCP_LICENSE_KEY": "your-license-key" } } } } ```

Claude Desktop

**Configuration Path:** `~/Library/Application Support/Claude/claude_desktop_config.json` **Remote Setup (Requires `mcp-remote` adapter):** ```json { "mcpServers": { "ClickUp": { "command": "npx", "args": [ "-y", "mcp-remote", "https://clickup-mcp.taazkareem.com/mcp", "--header", "X-License-Key: your-license-key" ] } } } ```

Claude Code (CLI)

Run this command in your terminal: ```bash claude mcp add --transport http ClickUp https://clickup-mcp.taazkareem.com/mcp \ --header "X-License-Key: your-license-key" ```

n8n

**Option A: Remote / Streamable HTTP (Recommended)** 1. In n8n, add an **"MCP Client"** node. 2. Set Connection Type to `Streamable HTTP`. 3. Auth Type: `Multiple Headers Auth`. 4. Header: `X-License-Key` Value: `your-license-key` 5. URL: `https://clickup-mcp.taazkareem.com/mcp` **Option B: Self-Hosted Docker** Run the container: ```bash docker run -d -p 3231:3231 ghcr.io/taazkareem/clickup-mcp-server:latest ``` In n8n, use URL: `http://host.docker.internal:3231/mcp`

Codex (CLI, Desktop, IDE)

Codex clients (CLI, Desktop App, and VS Code extension) share a single source of truth for configuration. **Configuration Paths:** - **Global:** `~/.codex/config.toml` - **Local:** `/.codex/config.toml` **Option A: Remote / Streamable HTTP (Easiest)** ```toml [mcp_servers.ClickUp] url = "https://clickup-mcp.taazkareem.com/mcp" http_headers = { "X-License-Key" = "your-license-key" } ``` **Option B: Local / STDIO** ```toml [mcp_servers.ClickUp] command = "npx" args = ["-y", "@taazkareem/clickup-mcp-server@latest"] env = { CLICKUP_API_KEY = "your-api-key", CLICKUP_TEAM_ID = "your-team-id", CLICKUP_MCP_LICENSE_KEY = "your-license-key" } ``` **Quick Tips:** - **Codex CLI:** Run `codex mcp list` to verify. Use `codex mcp add ...` as a CLI alternative to editing the file. - **VS Code Extension:** Click **⚙ → MCP settings → Open config.toml**. - **Desktop App:** Go to **Settings → Integrations & MCP**.

ChatGPT (Developer Mode)

_Note: Requires a Business, Enterprise, or Edu workspace with Developer Mode enabled._ 1. **Enable Developer Mode:** Ask your workspace admin to enable this under **Workspace Settings → Permissions & Roles → Connected Data**. 2. **Connect MCP:** Go to **Settings → Connectors** and toggle **Developer Mode** on. 3. **Add Custom Connector:** - Click **Add connector** (or "Create custom connector"). - Choose **MCP** as the source type. 4. **Configure:** - **Server URL:** `https://clickup-mcp.taazkareem.com/mcp` - **Authentication:** Add HTTP header `X-License-Key: your-license-key`. 5. **Use:** Start a Developer Mode chat and select your ClickUp connector via **Add sources**.

Augment Code

**Configuration Path:** `/.augment/settings.json` ```json { "mcpServers": { "ClickUp": { "url": "https://clickup-mcp.taazkareem.com/mcp", "headers": { "X-License-Key": "your-license-key" } } } } ```

Auggie CLI

Run this command in your terminal: ```bash auggie mcp add ClickUp --url https://clickup-mcp.taazkareem.com/mcp \ --header "X-License-Key: your-license-key" ```

Windsurf

**Configuration Path:** `/.codeium/windsurf/mcp_config.json` **Option A: Remote / Streamable HTTP (Easiest)** ```json { "mcpServers": { "ClickUp": { "url": "https://clickup-mcp.taazkareem.com/mcp", "headers": { "X-License-Key": "your-license-key" } } } } ``` **Option B: Local / STDIO** ```json { "mcpServers": { "ClickUp": { "command": "npx", "args": ["-y", "@taazkareem/clickup-mcp-server@latest"], "env": { "CLICKUP_API_KEY": "your-api-key", "CLICKUP_TEAM_ID": "your-team-id", "CLICKUP_MCP_LICENSE_KEY": "your-license-key" } } } } ```

### 3. Restart Restart your MCP Host (e.g., Cursor IDE). The server will validate your License Key and start automatically. --- ## 🛠️ Available Tools

👇 Click to view all 150 available tools

--- ## ⚙️ Advanced Configuration ### Filter Available Tools 💡 **Pro Tip!** Reduce context noise for the AI by limiting available tools. There are 3 ways to do this. You can filter by exact tool name, by tool category, by personas (presets), or a combination of all three. **Local (Environment Variable):** ```json "ENABLED_TOOLS": "tool_1,tool_2,tool_3", "ENABLED_CATEGORIES": "task,time_tracking,workspace" ``` -or- **Hermes (YAML):** ```yaml mcp_servers: clickup: env: ENABLED_TOOLS: "tool_1,tool_2,tool_3" ENABLED_CATEGORIES: "task,time_tracking,workspace" ``` -or- **Remote (Header):** ```json "X-Enabled-Tools": "tool_1,tool_2,tool_3", "X-Enabled-Categories": "task,time_tracking,workspace" ``` ### Preset Configurations Simplify setup by using **Personas**. You can set a persona via the `CLICKUP_MCP_PERSONA` environment variable or the `X-Persona` HTTP header to automatically filter a set of tools. Multiple personas can be combined (e.g., `"X-Persona": "task_worker,time_specialist"`).

Persona	Description	Target Use Case
📋 `auditor`	Read-only access	View tasks, goals, docs, and chat (Read-only).
👷 `task_worker`	Daily management	Task CRUD, time tracking, and checklists.
⏱️ `time_specialist`	Time tracking focus	Time logs, timesheets, and entry history.
🏗️ `project_manager`	High-level control	Spaces, folders, lists, and bulk operations.
📚 `content_manager`	Communication	Docs, chat, comments, and attachments.
🏢 `workspace_admin`	Admin control	Permissions, guests, and audit logs.
💻 `developer`	Programmatic	Webhooks, custom fields, bulk automation.
🛡️ `safe_power_user`	Full access	All tools except destructive deletes/removals.

**Local (Environment Variable):** ```json "CLICKUP_MCP_PERSONA": "task_worker" ``` -or- **Remote (Header):** ```json "X-Persona": "task_worker" ``` > **💡 Need to customize?** To view the exact tools included in each preset or to build a custom list based on a persona, see the [Personas Reference Guide](./docs/reference/personas.md). --- ### 🌍 Multi-Workspace Support Simultaneously federate OAuth and multiple API keys to manage tasks across different authorized ClickUp accounts/workspaces in a single session. Easily move or duplicate tasks between workspaces, configure AI Agents for cross-workspace automation, and more. **Remote (Headers):** ```json { "mcpServers": { "ClickUp": { "url": "https://clickup-mcp.taazkareem.com/mcp", "headers": { "X-License-Key": "your-license-key", "X-ClickUp-Additional-Keys": "shared_ws_api_key1,shared_ws_api_key2" } } } } ``` --- ## ❓ FAQ **Why isn't this free anymore?** Building reliable MCP integrations requires significant maintenance. Moving to a paid model allows us to support this as a product rather than a hobby, ensuring compatibility with API changes. **I have an old version. Will it stop working?** Existing local clones will continue to work, but you will not receive updates, bug fixes, or support without a license. **How do I get support?** Premium users get priority support. Please [open an issue](https://github.com/TaazKareem/clickup-mcp-server/issues) in this repository. --- ## ⚖️ Disclaimer Originally developed as open source and refined during a consultancy with ClickUp, this project is now independently maintained. This software makes use of third-party APIs and may reference trademarks or brands owned by third parties. The use of such APIs or references does not imply any affiliation with or endorsement by the respective companies. All trademarks and brand names are the property of their respective owners. This project is an independent work and is not officially associated with or sponsored by any third-party company mentioned. By using this software, you agree to our [Terms of Service](TERMS_OF_SERVICE.md) and acknowledge our [Privacy Policy](PRIVACY.md).

_{Created by taazkareem}