The ClickUp MCP Server provides a Model Context Protocol interface that enables AI assistants to interact with and manage ClickUp workspaces. Key capabilities include:
- Task Management: Create and update tasks with properties like name, description, status, priority, assignees, due date, time estimate, and tags.
- Team & List Management: Retrieve accessible workspaces and lists within folders.
- Board Management: Create new boards within a space.
- Space Management: Retrieve, create, update, and delete spaces.
- Folder Management: Retrieve, create, update, and delete folders within spaces.
- Custom Field Management: Retrieve custom fields for lists and manage custom field values on tasks.
- Doc Management: Search, create, and edit docs and doc pages.
- View Management: Retrieve, create, update, and delete views for various resources, and get tasks for specific views.
Enables interaction with ClickUp workspaces, providing tools for task management (creating and updating tasks), team and list management (retrieving teams and lists), and board management (creating boards).
ClickUp MCP Server
A Model Context Protocol server implementation for ClickUp integration, enabling AI assistants to interact with ClickUp workspaces.
This server runs via Stdio as per the MCP specification when invoked by an MCP client.
Quick Start
This server uses your ClickUp Personal API Token for authentication.
- Generate a Personal API Token: In your ClickUp settings, navigate to "My Settings" > "Apps" and generate a token.
- Configure your MCP Client (e.g., Claude for Desktop): Set the required environment variable when configuring the server for your client.
Example configuration snippet for an MCP client:
- Restart your MCP Client.
The server will be automatically downloaded and started by the MCP client when needed.
Installing via Smithery
To install ClickUp MCP Server for Claude Desktop automatically via Smithery:
Environment Variables
Required
CLICKUP_PERSONAL_TOKEN
: Your ClickUp Personal API Token. This is essential for the server to authenticate with the ClickUp API.
Optional
LOG_LEVEL
: Logging level for the server. Supportserror
,warn
,info
,debug
. Defaults toinfo
.ENCRYPTION_KEY
: A persistent 32-byte hex-encoded key. The configuration system (src/config/app.config.ts
) loads or generates this key, andsrc/security.ts
contains encryption/decryption functions. However, this mechanism is currently not used for encrypting theCLICKUP_PERSONAL_TOKEN
within theClickUpService
's Personal API Token authentication flow.PORT
: Server port. This is not used by the default Stdio MCP server mode but might be relevant if an HTTP transport or additional HTTP features (like a separate health check endpoint) were explicitly added. Defaults to3000
in the config if read.
Available Tools
The following MCP tools are currently implemented:
Task Management
clickup_create_task
: Create a new task in a ClickUp list.- Requires:
list_id
,name
. - Optional:
description
,status
,priority
,assignees
,due_date
,time_estimate
,tags
.
- Requires:
clickup_update_task
: Update an existing task's properties.- Requires:
task_id
. - Optional: Any writable
ClickUpTask
properties.
- Requires:
Team & List Management
clickup_get_teams
: Retrieve all accessible teams (Workspaces in ClickUp API v2).clickup_get_lists
: Get all lists in a specific folder.- Requires:
folder_id
.
- Requires:
Board Management
clickup_create_board
: Create a new board in a ClickUp space.- Requires:
space_id
,name
.
- Requires:
Space Management
clickup_get_spaces
: Retrieves all Spaces for a given Workspace (Team).- Requires:
team_id
(Workspace ID). - Optional:
archived
(boolean, defaults tofalse
).
- Requires:
clickup_create_space
: Creates a new Space within a Workspace.- Requires:
team_id
(Workspace ID),name
. - Optional:
multiple_assignees
(boolean),features
(object with feature flags likedue_dates
,time_tracking
, etc.).
- Requires:
clickup_get_space
: Retrieves details for a specific Space.- Requires:
space_id
.
- Requires:
clickup_update_space
: Updates an existing Space.- Requires:
space_id
. - Optional:
name
,color
,private
,admin_can_manage
,archived
,features
.
- Requires:
clickup_delete_space
: Deletes a Space.- Requires:
space_id
.
- Requires:
Folder Management
clickup_get_folders
: Retrieves all Folders within a given Space.- Requires:
space_id
. - Optional:
archived
(boolean, defaults tofalse
).
- Requires:
clickup_create_folder
: Creates a new Folder within a Space.- Requires:
space_id
,name
.
- Requires:
clickup_get_folder
: Retrieves details for a specific Folder.- Requires:
folder_id
.
- Requires:
clickup_update_folder
: Updates an existing Folder.- Requires:
folder_id
,name
.
- Requires:
clickup_delete_folder
: Deletes a Folder.- Requires:
folder_id
.
- Requires:
Custom Field Management
clickup_get_custom_fields
: Retrieves all accessible Custom Fields for a given List.- Requires:
list_id
.
- Requires:
clickup_set_task_custom_field_value
: Sets the value of a Custom Field on a specific task.- Requires:
task_id
,field_id
,value
. - Optional:
value_options
(object, e.g.,{ "time": true }
for date fields).
- Requires:
clickup_remove_task_custom_field_value
: Removes/clears the value of a Custom Field from a specific task.- Requires:
task_id
,field_id
.
- Requires:
Doc Management
Note: ClickUp's API for Docs (especially v2, with some operations now using v3) has limitations. Content is primarily handled as Markdown. Advanced formatting or complex embeds might not be fully supported. Direct document deletion via API is not currently supported by ClickUp's V3 /docs endpoint; manage Doc lifecycle through archiving or page manipulation.
clickup_search_docs
: Searches for Docs within a Workspace (Team).- Requires:
workspace_id
. - Optional:
query
(string),include_archived
(boolean).
- Requires:
clickup_create_doc
: Creates a new Doc.- Requires:
workspace_id
,name
. - Optional:
parent
(object withid
andtype
),visibility
(string: "private", "workspace", "public"),create_page
(boolean).
- Requires:
clickup_get_doc_pages
: Retrieves the list of pages within a specific Doc.- Requires:
doc_id
.
- Requires:
clickup_create_doc_page
: Creates a new page within a specific Doc.- Requires:
workspace_id
,doc_id
,name
(page title). - Optional:
content
(Markdown),orderindex
(number, though v3 API may not use it),parent_page_id
(string),sub_title
(string),content_format
(string).
- Requires:
clickup_get_doc_page_content
: Retrieves the content (Markdown) of a specific Doc page.- Requires:
workspace_id
,doc_id
,page_id
. - Optional:
content_format
(string).
- Requires:
clickup_edit_doc_page_content
: Updates the content and/or title of a specific Doc page.- Requires:
workspace_id
,doc_id
,page_id
,content
(Markdown). - Optional:
title
(string, maps to API 'name'),sub_title
(string),content_edit_mode
(string: "replace", "append", "prepend"),content_format
(string).
- Requires:
View Management
clickup_get_views
: Retrieves all Views for a given parent resource (Team, Space, Folder, or List).- Requires:
parent_id
(ID of the parent resource),parent_type
(string: "team", "space", "folder", or "list").
- Requires:
clickup_create_view
: Creates a new View within a Team, Space, Folder, or List.- Requires:
parent_id
,parent_type
,name
(string: name of the new View),type
(string: type of the View, e.g., "list", "board", "calendar", "gantt"). - Optional:
grouping
,divide
,sorting
,filters
,columns
,team_sidebar
,settings
(objects defining view configurations).
- Requires:
clickup_get_view_details
: Retrieves details for a specific View.- Requires:
view_id
.
- Requires:
clickup_update_view
: Updates an existing View.- Requires:
view_id
. - Optional:
name
(string),grouping
,divide
,sorting
,filters
,columns
,team_sidebar
,settings
.
- Requires:
clickup_delete_view
: Deletes a View.- Requires:
view_id
.
- Requires:
clickup_get_view_tasks
: Retrieves tasks belonging to a specific View.- Requires:
view_id
. - Optional:
page
(number: 0-indexed page number for pagination).
- Requires:
Development
- Clone the repository:
- Install dependencies:
- Create a
.env
file in the root directory and add yourCLICKUP_PERSONAL_TOKEN
: - Start in development mode (Stdio):
The server will listen for MCP messages on stdin/stdout.This uses
ts-node-dev
to runsrc/index.ts
. - Build for production:This compiles TypeScript to
dist/
. - Run tests:This runs Jest unit tests located in
src/__tests__
. Ensure you have a.env.test
file (seesrc/__tests__/setup.ts
).
Testing with MCP Inspector
You can test the server locally using the MCP Inspector:
- Ensure your
CLICKUP_PERSONAL_TOKEN
is available. You can either:- Set it in your shell environment before running the inspector.
- Set it within the MCP Inspector UI if it provides an option for server environment variables.
- Have it in your local
.env
file (assrc/index.ts
loadsdotenv
).
- Run the Inspector with the server:The Inspector UI should launch, allowing you to connect to the server and call its tools.
Security
- Authenticates using your ClickUp Personal API Token. Keep this token secure and confidential. Treat it like a password.
- The server expects the
CLICKUP_PERSONAL_TOKEN
to be provided via an environment variable by the consuming MCP client or development environment. - The configuration system includes logic for an
ENCRYPTION_KEY
andsrc/security.ts
has encryption functions, but this is not currently applied to the Personal API Token by theClickUpService
. - No sensitive data (like the token itself) is logged by default with
LOG_LEVEL=info
. Debug level might log more details. - Rate limiting for ClickUp API calls is handled by logging remaining requests (see
ClickUpService
).
Troubleshooting
Common Issues
- Authentication Errors (401 from ClickUp API)
- Verify your
CLICKUP_PERSONAL_TOKEN
environment variable is correctly set and accessible by the server process. - Ensure the token is valid and not revoked in your ClickUp settings.
- Check server logs for messages from
ClickUpService
regarding authentication.
- Verify your
- Rate Limiting by ClickUp API
- The server logs rate limit information from ClickUp API responses.
- If rate limits are hit frequently, this indicates high usage. The server itself does not implement queuing or complex backoff beyond what
axios
might do by default.
- Server Not Starting / MCP Inspector Connection Issues
- Ensure
CLICKUP_PERSONAL_TOKEN
is set. - If using
npm run dev
, check for TypeScript orts-node-dev
errors in the console. - If using MCP Inspector with
node --loader ts-node/esm src/index.ts
, ensurets-node
and project dependencies are correctly installed. - Check for console errors from
src/index.ts
orClickUpService
.
- Ensure
Getting Server Logs
- When run via
npm run dev
ornpm start
, logs go to the console. - If run by an MCP client (like Claude for Desktop), logs are typically managed by that client. For Claude for Desktop, logs can often be found at:
- Windows:
%USERPROFILE%\AppData\Local\Claude\Logs\mcp\<server_name_and_id>\<process_id>.log
(path may vary slightly) - macOS:
~/Library/Logs/Claude/mcp/<server_name_and_id>\<process_id>.log
(path may vary slightly)
- Windows:
Support
If you find this project helpful, consider buying me a coffee to support ongoing development and maintenance.
License
MIT License - see LICENSE file for details
You must be authenticated.
remote-capable server
The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.
This server integrates AI assistants with ClickUp workspaces, enabling task, team, list, and board management through a secure OAuth2 authentication process.
Related Resources
Related MCP Servers
- AsecurityAlicenseAqualityEnables AI integrations with ClickUp tasks, supporting resource management, task operations, workspace organization, and AI-powered task recommendations through a standardized protocol.Last updated -18313170TypeScriptMIT License
- -securityAlicense-qualityThis server implementation allows AI assistants to interact with Asana's API, enabling users to manage tasks, projects, workspaces, and comments through natural language requests.Last updated -342TypeScriptMIT License
- AsecurityFlicenseAqualityAn MCP server that allows AI assistants to interact with the ServiceTitan API, requiring client credentials for authentication.Last updated -454TypeScript
- -securityFlicense-qualityA Cloudflare Workers-based server implementing the Model Context Protocol that enables AI assistants like Claude to securely access external tools through OAuth authentication.Last updated -14TypeScript