ClickUp MCP server for AI agents

The ClickUp MCP Integration server allows Large Language Models to interact with your ClickUp workspace, providing access to tasks, documents, custom fields, and more through the Model Context Protocol (MCP).

Installation and Setup

Prerequisites

Docker installed on your system
ClickUp account with API access
Your ClickUp API token and Workspace ID

Obtaining ClickUp Credentials

Getting Your API Token

Log in to your ClickUp account at app.clickup.com
Navigate to user settings by clicking your profile picture (bottom-left corner)
Select "Settings"
Click on "Apps" in the left sidebar
Under "API Token", click "Generate" if you don't have a token
Copy the generated API token

Finding Your Workspace ID

Open ClickUp in your web browser
Look at the URL when you're in your workspace
The Workspace ID is the numeric value in the URL: https://app.clickup.com/{workspace_id}/home
Copy this number

Setting Up the MCP Server

For Cline Users

Open VSCode or Jetbrains IDEs and go to Cline
Navigate to MCP Servers → Installed → Configure MCP Servers
Add the following to your cline_mcp_settings.json inside the mcpServers key:

"clickup": {
  "command": "docker",
  "args": [
    "run",
    "-i",
    "--rm",
    "-e",
    "CLICKUP_API_TOKEN",
    "-e",
    "CLICKUP_WORKSPACE_ID",
    "your-docker-repository"
  ],
  "env": {
    "CLICKUP_API_TOKEN": "your-api-token",
    "CLICKUP_WORKSPACE_ID": "your-workspace-id"
  }
}

For Claude Desktop Users

Open the Claude Desktop configuration file:
- Windows: C:\Users\YourUsername\AppData\Roaming\Claude\claude_desktop_config.json
- Mac: ~/Library/Application\ Support/Claude/claude_desktop_config.json
Add the following to your claude_desktop_config.json inside the mcpServers key:

"clickup": {
  "command": "docker",
  "args": [
    "run",
    "-i",
    "--rm",
    "-e",
    "CLICKUP_API_TOKEN",
    "-e",
    "CLICKUP_WORKSPACE_ID",
    "your-docker-repository"
  ],
  "env": {
    "CLICKUP_API_TOKEN": "your-api-token",
    "CLICKUP_WORKSPACE_ID": "your-workspace-id"
  }
}

Save the configuration file
Restart Claude Desktop to apply the changes

Available Tools and Usage

Task Management

The MCP server provides several tools for managing ClickUp tasks:

Creating tasks: Create new tasks in your workspace
```
clickup_create_task
```
Retrieving tasks: Get task information using ID or custom ID
```
clickup_get_task
clickup_get_task_by_custom_id
```

Updating tasks: Modify existing tasks

clickup_update_task
clickup_update_task_by_custom_id

Listing tasks: Get all tasks from a specific list with filtering options
```
get_list_tasks
```

Document Management

For ClickUp documents, you can:

Search documents
```
clickup_search_docs
```
Create new documents
```
clickup_create_doc
```

Manage document pages

clickup_get_doc_pages
clickup_get_page
clickup_create_page
clickup_edit_page

Custom Fields Management

Custom fields can be managed with:

Retrieving custom fields
```
clickup_get_list_custom_fields
```

Setting custom field values

clickup_set_custom_field_value
clickup_set_custom_field_value_by_custom_id

Workspace Structure Management

Manage your ClickUp workspace structure with:

Viewing workspace hierarchy
```
get_spaces
get_folders
get_lists
```
Creating lists
```
create_list
```

Assignee Management

List available assignees
```
get_list_assignees
```

Troubleshooting

If you encounter issues with the MCP server:

Authentication Errors

Verify your API token is correct
Ensure the API token has the necessary permissions
Check that your workspace ID is correct

Task Access Issues

Confirm you have access to the tasks you're trying to retrieve
Verify the task IDs are correct and exist in your workspace
Check if the tasks might be in an archived state

Connection Problems

Ensure your Docker service is running properly
Check your network connection
Verify the environment variables are correctly set in your MCP configuration

How to add this MCP server to Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > MCP and click "Add new global MCP server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "cursor-rules-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "cursor-rules-mcp"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explictly ask the agent to use the tool by mentioning the tool name and describing what the function does.