clickup-mcp-server

taazkareem/clickup-mcp-server

3.4

If you are the rightful owner of clickup-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

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

ClickUp MCP Server - Premium

ClickUp MCP Server Premium Image

npm version npm downloads Top 3 on Google Trending MCP Server Maintained


Properly Connect ClickUp to AI Agents and Agentic Workflows

A high-performance Model Context Protocol (MCP) server for managing tasks, checklists, 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


✨ Features

🔐 Hybrid Authentication
MCP spec compliant OAuth 2.1 with advanced security hardening. Backwards compatible with API Key/Team ID.
🔍 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
Create, update, move, delete, duplicate, and link tasks. Supports bulk operations, nested subtasks, checklists, natural language dates, custom task IDs, custom task types, and custom fields.
⏱️ Time Tracking
Start/stop timers, log manual entries, 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.
💬 Chat & Collaboration
Send/retrieve messages in channels and comments with threaded replies, rich-text conversion and user @mention support.
🌳 Workspace Control
Create and navigate spaces, folders, lists, and tags. Switch workspaces mid-conversation.
🧠 Smart Defaults
Session-isolated caching for fast, secure multi-tenant operation.

💎 Premium Access

This project operates on a Sponsorware model. A license grants full access to all 66+ premium tools with any of the following plans:

Monthly Plan ($9/mo)Annual Subscription ($59/yr)Lifetime Access ($89 w/ code)
• Pay-as-you-go flexibility
• 3 device activations
• Cancel anytime
• ONLY $4.92/mo
• 3 device activations
• Priority bug fixes
25% OFF code: MAR25
• 3 device activations
Best Value (One-time payment)

⚡️ Instant Delivery: Your License Key is delivered immediately via Polar.sh. Total setup time is under 2 minutes.

Purchase License


🚀 Quick Start & Installation

1. Prerequisites

  • License Key: See above

  • ClickUp Credentials: (Optional) API Key & Team ID

    How to find your credentials?

    ClickUp API Key:

    1. Log into ClickUp and go to ClickUp Settings → Apps.
    2. Click Generate under "API Token" (or copy your existing one).

    ClickUp Team ID:

    1. Open ClickUp in your browser.
    2. Look at the URL: https://app.clickup.com/1234567/v/li/987654321.
    3. The first number (1234567) directly after clickup.com/ is your Team ID (Workspace ID).

2. Choose your Integration

  Cursor

Configuration Path: <project-root>/.cursor/mcp.json

Option A: Cloud / Remote (Easiest)

{
  "mcpServers": {
    "ClickUp": {
      "url": "https://clickup-mcp.taazkareem.com/mcp",
      "headers": {
        "X-License-Key": "your-license-key"
      }
    }
  }
}

Option B: Local (stdio)

{
  "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"
      }
    }
  }
}

  Windsurf

Configuration Path: <project-root>/.codeium/windsurf/mcp_config.json

Option A: Cloud / Remote (Easiest)

{
  "mcpServers": {
    "ClickUp": {
      "url": "https://clickup-mcp.taazkareem.com/mcp",
      "headers": {
        "X-License-Key": "your-license-key"
      }
    }
  }
}

Option B: Local (stdio)

{
  "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: <project-root>/.vscode/mcp.json

Option A: Cloud / Remote (Easiest)

{
  "mcpServers": {
    "ClickUp": {
      "url": "https://clickup-mcp.taazkareem.com/mcp",
      "headers": {
        "X-License-Key": "your-license-key"
      }
    }
  }
}

Option B: Local (stdio)

{
  "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: <project-root>/.roo/mcp.json

Option A: Cloud / Remote (Easiest)

{
  "mcpServers": {
    "ClickUp": {
      "url": "https://clickup-mcp.taazkareem.com/mcp",
      "headers": {
        "X-License-Key": "your-license-key"
      }
    }
  }
}

Option B: Local (stdio)

{
  "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):

{
  "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:

claude mcp add --transport http ClickUp https://clickup-mcp.taazkareem.com/mcp \
  --header "X-License-Key: your-license-key"

  n8n

Option A: Cloud / Remote (Recommended)

  1. In n8n, add an "MCP Client" node.
  2. Set Connection Type to HTTP Streamable.
  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:

docker run -d -p 3231:3231 ghcr.io/taazkareem/clickup-mcp-server:latest

In n8n, use URL: http://host.docker.internal:3231/mcp

  Gemini CLI

Configuration Path: ~/.gemini/settings.json

{
  "mcpServers": {
    "ClickUp": {
      "httpUrl": "https://clickup-mcp.taazkareem.com/mcp",
      "headers": { "X-License-Key": "your-license-key" }
    }
  }
}

  Antigravity

Configuration Path: ~/.gemini/antigravity/mcp_config.json

{
  "mcpServers": {
    "ClickUp": {
      "serverUrl": "https://clickup-mcp.taazkareem.com/mcp",
      "headers": { "X-License-Key": "your-license-key" }
    }
  }
}

  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: <project-root>/.codex/config.toml

Option A: Cloud / Remote (Easiest)

[mcp_servers.ClickUp]
url = "https://clickup-mcp.taazkareem.com/mcp"
http_headers = { "X-License-Key" = "your-license-key" }

Option B: Local (stdio)

[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: <project-root>/.augment/settings.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:

auggie mcp add ClickUp --url https://clickup-mcp.taazkareem.com/mcp \
  --header "X-License-Key: your-license-key"

  OpenClaw (via mcporter)

1. Enable the mcporter skill in ~/.openclaw/openclaw.json:

{"skills": {"allowBundled": ["mcporter"]}}

2. Configure

The fastest way to configure the server is using the mcporter CLI. Run one of the following commands in your terminal:

Option A: Local (Recommended) Saves to <project-root>/config/mcporter.json

mcporter config add ClickUp https://clickup-mcp.taazkareem.com/mcp \
  --auth oauth \
  --header "X-License-Key=your-license-key"

Option B: Global Saves to ~/.mcporter/mcporter.json

mcporter config add ClickUp https://clickup-mcp.taazkareem.com/mcp \
  --scope home \
  --auth oauth \
  --header "X-License-Key=your-license-key"

3. Authenticate — run once to authorize via browser (tokens are cached):

mcporter auth ClickUp

4. Use:

mcporter call ClickUp.get_workspace_hierarchy team_id=0123456789

Tip: Since mcporter is a one-shot CLI client, if using multiple workspaces, always pass team_id to target the correct workspace.

 Other (Custom Agents, etc.)

For most MCP-compliant hosts (e.g. Smithery, MCP Inspector, custom GUIs):

  • Server URL: https://clickup-mcp.taazkareem.com/mcp
  • Auth Header: X-License-Key: your-license-key (Required for HTTP/SSE connections)

Advanced: OpenAI Agents SDK For developers building custom agents.

Python SDK:

from agents import Agent, Runner
from agents.mcp import MCPServerStreamableHttp

async with MCPServerStreamableHttp(
    name="clickup",
    params={
        "url": "https://clickup-mcp.taazkareem.com/mcp",
        "headers": {"X-License-Key": "your-license-key"},
    },
) as server:
    agent = Agent(
        name="Assistant",
        instructions="Use the ClickUp MCP tools when helpful.",
        mcp_servers=[server],
    )
    result = await Runner.run(agent, "List my workspaces.")

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 66 available tools
CategoryToolDescription
Workspaceget_workspace_hierarchyGet workspace structure
get_workspace_membersGet all workspace members
find_member_by_nameFind member by name or email
Taskscreate_taskCreate a task
get_taskGet single task details
update_taskModify task properties
set_task_custom_fieldSet a custom field value
move_taskMove task to new list
duplicate_taskCopy task
delete_taskRemove task
add_task_to_listAssociate task with additional list (TIML)
remove_task_from_listRemove task list association (TIML)
create_bulk_tasksCreate multiple tasks
update_bulk_tasksUpdate multiple tasks
move_bulk_tasksMove multiple tasks
delete_bulk_tasksDelete multiple tasks
get_workspace_tasksSearch tasks with Deep Search filtering
get_task_commentsGet comments on a task
create_task_commentAdd a comment to a task
attach_task_fileAttach file to a task
add_task_linkLink two tasks together
get_task_linksGet task dependencies
delete_task_linkRemove task dependency
Checklistscreate_checklistAdd a checklist to a task
edit_checklistRename or reorder a checklist
delete_checklistDelete a checklist and all its items
create_checklist_itemAdd an item to a checklist
edit_checklist_itemUpdate item (rename, check/uncheck, assign)
delete_checklist_itemRemove an item from a checklist
Listscreate_listCreate list in space
create_list_in_folderCreate list in folder
get_listGet list details
update_listUpdate list properties
move_listMove list to new Space/Folder
delete_listDelete a list
get_custom_fieldsGet custom field definitions (workspace/space/folder/list scope)
Folderscreate_folderCreate folder
get_folderGet folder details
update_folderUpdate folder properties
move_folderMove folder to new Space
delete_folderDelete a folder
Tagsget_space_tagsGet space tags
create_space_tagCreate tag
update_space_tagUpdate tag properties
delete_space_tagDelete a tag
add_tag_to_taskAdd tag to task
remove_tag_from_taskRemove tag from task
Time Trackingget_task_time_entriesGet time entries with date filters
get_workspace_time_entriesSearch all time entries
start_time_trackingStart time tracking
stop_time_trackingStop current time tracking
add_time_entryAdd manual time entry
delete_time_entryDelete time entry
get_current_time_entryGet running timer
Docscreate_documentCreate a document
get_documentGet a document
list_documentsList documents
list_document_pagesList pages in a document
get_document_pagesGet page content
create_document_pageAdd page to document
update_document_pageUpdate page content
Chatcreate_chat_channelCreate a chat channel
get_chat_channelsList chat channels
create_chat_messageSend a message to a channel
get_chat_messagesGet message history
Feedbacksubmit_feedbackSubmit feedback or bug reports

See for parameters and advanced usage.


⚙️ Advanced Configuration

Filter Available Tools

💡 Pro Tip! Reduce context noise for the AI by limiting available tools.

Local (Environment Variable):

"ENABLED_TOOLS": "tool_1,tool_2,tool_3"

-or- Remote (Header):

"X-Enabled-Tools": "tool_1,tool_2,tool_3"

Preset Configurations

Here are copy-pasteable recommended configurations for common agent personas. You can use these in your mcp.json (env) or via HTTP headers. Customization is easy - just add or remove tools you don't need.

📋 Auditor

Best for agents that need to view data without making any changes.

HTTP Header: X-Enabled-Tools: get_workspace_hierarchy,get_workspace_tasks,get_task,get_list,get_folder,get_custom_fields,get_task_comments,get_task_time_entries,get_workspace_time_entries,get_current_time_entry,get_task_links,get_space_tags,get_workspace_members,find_member_by_name,get_chat_channels,get_chat_messages,get_document,list_documents,list_document_pages,get_document_pages,submit_feedback

JSON / Env:

"env": {
  "ENABLED_TOOLS": "get_workspace_hierarchy,get_workspace_tasks,get_task,get_list,get_folder,get_custom_fields,get_task_comments,get_task_time_entries,get_workspace_time_entries,get_current_time_entry,get_task_links,get_space_tags,get_workspace_members,find_member_by_name,get_chat_channels,get_chat_messages,get_document,list_documents,list_document_pages,get_document_pages,submit_feedback"
}
👷 Task Worker

Focused on day-to-day task management. Can create/update tasks and track time, but cannot delete tasks or modify structure (Lists/Folders).

HTTP Header: X-Enabled-Tools: get_workspace_hierarchy,get_workspace_tasks,get_task,get_list,get_folder,get_custom_fields,create_task,update_task,set_task_custom_field,move_task,duplicate_task,create_task_comment,get_task_comments,attach_task_file,start_time_tracking,stop_time_tracking,add_tag_to_task,remove_tag_from_task,add_task_link,delete_task_link,get_task_links,add_task_to_list,remove_task_from_list,create_checklist,edit_checklist,delete_checklist,create_checklist_item,edit_checklist_item,delete_checklist_item,find_member_by_name,submit_feedback

JSON / Env:

"env": {
  "ENABLED_TOOLS": "get_workspace_hierarchy,get_workspace_tasks,get_task,get_list,get_folder,get_custom_fields,create_task,update_task,set_task_custom_field,move_task,duplicate_task,create_task_comment,get_task_comments,attach_task_file,start_time_tracking,stop_time_tracking,add_tag_to_task,remove_tag_from_task,add_task_link,delete_task_link,get_task_links,add_task_to_list,remove_task_from_list,create_checklist,edit_checklist,delete_checklist,create_checklist_item,edit_checklist_item,delete_checklist_item,find_member_by_name,submit_feedback"
}
⏱️ Time Specialist

For agents dedicated to logging time and generating timesheets.

HTTP Header: X-Enabled-Tools: get_workspace_hierarchy,get_workspace_tasks,get_task,get_task_time_entries,get_workspace_time_entries,get_current_time_entry,start_time_tracking,stop_time_tracking,add_time_entry,delete_time_entry,submit_feedback

JSON / Env:

"env": {
  "ENABLED_TOOLS": "get_workspace_hierarchy,get_workspace_tasks,get_task,get_task_time_entries,get_workspace_time_entries,get_current_time_entry,start_time_tracking,stop_time_tracking,add_time_entry,delete_time_entry,submit_feedback"
}
📚 Content Manager

For agents managing documentation and communication.

HTTP Header: X-Enabled-Tools: get_workspace_hierarchy,get_workspace_tasks,get_task,get_task_comments,create_task_comment,find_member_by_name,create_document,get_document,list_documents,list_document_pages,get_document_pages,create_document_page,update_document_page,create_chat_channel,get_chat_channels,create_chat_message,get_chat_messages,submit_feedback

JSON / Env:

"env": {
  "ENABLED_TOOLS": "get_workspace_hierarchy,get_workspace_tasks,get_task,get_task_comments,create_task_comment,find_member_by_name,create_document,get_document,list_documents,list_document_pages,get_document_pages,create_document_page,update_document_page,create_chat_channel,get_chat_channels,create_chat_message,get_chat_messages,submit_feedback"
}
🛡️ Safe Power User

Enabled everything except destructive tools. This configuration covers all 66 tools by default, only blocking the 9 specific deletion tools listed below. Useful for capable agents that need full access (including Folder/List management) but shouldn't destroy data.

HTTP Header: X-Disabled-Tools: delete_task,delete_bulk_tasks,delete_time_entry,delete_task_link,delete_list,delete_folder,delete_space_tag,delete_checklist,delete_checklist_item

JSON / Env:

"env": {
  "DISABLED_TOOLS": "delete_task,delete_bulk_tasks,delete_time_entry,delete_task_link,delete_list,delete_folder,delete_space_tag,delete_checklist,delete_checklist_item"
}

❓ 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 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.

Created by taazkareem