npm package: @houlak/clickup-mcp
Description: MCP server to interact with ClickUp
Author: Bruno Lorenzo
Latest version: 1.0.0

# 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](#features)
- [Prerequisites](#prerequisites)
- [Installation](#installation)
  - [Method 1: Direct Installation (Recommended for Development)](#method-1-direct-installation-recommended-for-development)
  - [Method 2: Global Installation (Coming Soon)](#method-2-global-installation-coming-soon)
- [Setup](#setup)
  - [Getting Your ClickUp API Token](#getting-your-clickup-api-token)
  - [Getting Your ClickUp Workspace ID](#getting-your-clickup-workspace-id)
  - [Configuring Your MCP Client](#configuring-your-mcp-client)
- [Available Tools](#available-tools)
  - [`get-tasks`](#get-tasks)
  - [`create-sub-task`](#create-sub-task)
  - [`search-documents`](#search-documents)
  - [`get-document`](#get-document)
  - [`get-document-pages`](#get-document-pages)
  - [`update-page`](#update-page)
- [Usage Examples](#usage-examples)
- [Troubleshooting](#troubleshooting)
- [Development](#development)
  - [Contributing](#contributing)
- [Roadmap](#roadmap)
- [License](#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](#setup) section)
- **ClickUp Workspace ID** (see [Setup](#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:**
   ```bash
   git clone <repository-url>
   cd ClickUp-MCP
   ```

2. **Install dependencies:**
   ```bash
   yarn install
   ```

3. **Build the project (if needed):**
  Just to ensure there isn't any error
   ```bash
   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:

```json
{
  "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:
```bash
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:

```bash
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](../../issues) with detailed information about the changes needed
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
2. Commit your changes (`git commit -m 'Add amazing feature'`)
3. Push to the branch (`git push origin feature/amazing-feature`)
4. Open a Pull Request

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.