ClickUp MCP Server

A Model Context Protocol (MCP) server that enables Large Language Models (LLMs) to interact with ClickUp tasks and workspaces. This server provides tools for retrieving task information and creating subtasks directly from your AI assistant.

Table of Contents

• Features
• Prerequisites
• Installation
  • Method 1: Direct Installation (Recommended for Development)
  • Method 2: Global Installation (Coming Soon)
• Setup
  • Getting Your ClickUp API Token
  • Getting Your ClickUp Workspace ID
  • Configuring Your MCP Client
• Available Tools
  • get-tasks
  • create-sub-task
  • search-documents
  • get-document
  • get-document-pages
  • update-page
• Usage Examples
• Troubleshooting
• Development
  • Contributing
• Roadmap
• License

Features

• Get Task Information: Retrieve detailed information about any ClickUp task by its ID
• Create Subtasks: Create new subtasks under existing tasks in specified lists
• Secure Authentication: Uses ClickUp API tokens for secure access
• Type-Safe: Built with TypeScript and Zod for robust type validation

Prerequisites

Before installing and using the ClickUp MCP server, ensure you have:

• Node.js (version 18 or higher)
• npm or yarn package manager
• ClickUp API Token (see Setup section)
• ClickUp Workspace ID (see Setup section)
• MCP-compatible LLM client (such as Claude Desktop, Cursor, or other MCP-enabled applications)

Installation

Method 1: Direct Installation (Recommended for Development)

1. Clone the repository:

   git clone <repository-url>
   cd ClickUp-MCP

2. Install dependencies:

   yarn install

3. Build the project (if needed): Just to ensure there isn't any error

   npx -Y tsx main.ts

Setup

Getting Your ClickUp API Token

1. Log in to your ClickUp account
2. Go to Settings → Apps → API
3. Click Generate to create a new API token
4. Copy the token

Getting Your ClickUp Workspace ID

1. Log in to your ClickUp account
2. Go to your Workspace settings
3. The Workspace ID can be found in the URL or workspace settings. The Workspace ID is the set of numbers that immediately follows "app.clickup.com/". For example, in the URL https://app.clickup.com/12345678/home, the Workspace ID is 12345678.
4. Save this value for configuration

Getting Your ClickUp User ID (Optional)

1. Log in to your ClickUp account
2. Create or access any document in your workspace
3. Use the get-document tool to retrieve document information
4. Look for the creator field in the response - this is your user ID
5. Alternatively, you can find your user ID in the ClickUp API by calling /user endpoint with your token

Note: This is optional but enables convenient "by me" shortcuts for document searches.

Configuring Your MCP Client

Add the following configuration to your mcp.json file:

{
  "mcpServers": {
    "clickup": {
      "command": "npx",
      "args": [
        "-y",
        "@houlak/clickup-mcp"
      ],
      "env": {
        "CLICKUP_API_TOKEN": "{Your ClickUp workspace ID}",
        "CLICKUP_WORKSPACE_ID": "3030784",
        "CLICKUP_USER_ID": "{Your ClickUp user ID (optional)}"
      }
    }
  }
}

Optional Configuration:

• CLICKUP_USER_ID: Your ClickUp user ID (optional). When configured, enables the "by me" shortcut in document searches and the search-my-documents tool.

Available Tools

get-tasks

Retrieves detailed information about a ClickUp task.

Parameters:

• taskId (string, required): The ClickUp task ID

Example Usage:

Get information about task "abc123"

create-sub-task

Creates a new subtask under an existing task.

Parameters:

• taskId (string, required): Parent task ID
• name (string, required): Name of the subtask
• listId (string, required): ID of the list where the subtask will be created
• description (string, optional): Description of the subtask

Example Usage:

Create a subtask named "Review documentation" under task "abc123" in list "def456"

search-documents

Search for documents in your ClickUp workspace.

Parameters:

• query (string, optional): Search query for document name
• creatorId (string, optional): User ID of the document creator (use "me" or "by-me" for your own documents if CLICKUP_USER_ID is configured)
• workspaceId (string, optional): Workspace ID (uses default if omitted)

Example Usage:

Find the document called "Project Plan"
Search for documents created by me
Search for documents created by user ID "12345678"

search-my-documents

Search for documents created by you (requires CLICKUP_USER_ID to be configured).

Parameters:

• query (string, optional): Search query for document name
• workspaceId (string, optional): Workspace ID (uses default if omitted)

Example Usage:

Find my documents containing "meeting notes"
Show all my documents

get-document

Retrieve information about a ClickUp document by its ID.

Parameters:

• documentId (string, required): The ClickUp document ID
• workspaceId (string, optional): Workspace ID (uses default if omitted)

Example Usage:

Show me the information for document "doc_abc123"

get-document-pages

Retrieve all pages within a ClickUp document.

Parameters:

• documentId (string, required): The ClickUp document ID
• workspaceId (string, optional): Workspace ID (uses default if omitted)

Example Usage:

Show me all pages in document "doc_abc123"

update-page

Update a specific page within a ClickUp document.

Parameters:

• documentId (string, required): The ClickUp document ID
• pageId (string, required): The page ID to update
• content (string, required): The new content (markdown)
• workspaceId (string, optional): Workspace ID (uses default if omitted)

Example Usage:

Update page "page_xyz" in document "doc_abc123" with new meeting notes

Usage Examples

Once configured, you can interact with ClickUp through your LLM:

• "Get details about task abc123"
• "Create a subtask called 'Write unit tests' under task xyz789 in list list123"
• "Show me the information for task def456 and then create a subtask for code review"

Troubleshooting

Common Issues

1. "Missing CLICKUP_API_TOKEN" Error

   • Ensure your API token is properly set in the .env file or MCP client configuration
   • Verify the token is valid and has the necessary permissions

2. "Task not found" Error

   • Double-check the task ID format
   • Ensure your API token has access to the workspace containing the task

3. "List not found" Error

   • Verify the list ID is correct
   • Ensure your API token has permissions to create tasks in the specified list

Debug Mode

To enable verbose logging, set the DEBUG environment variable:

DEBUG=clickup-mcp node main.ts

Using Inspector for Local Debugging

To test the MCP server locally with the Model Context Protocol Inspector, you can use the provided debug script:

yarn debug

This will launch the MCP server with the Inspector attached, allowing you to interactively test and debug your ClickUp integration.

Development

Contributing

1. Create a new Issues with detailed information about the changes needed
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.