ClickUp MCP Server

A Model Context Protocol (MCP) server that provides integration with the ClickUp API, allowing clients to interact with ClickUp tasks and lists through standardized MCP tools.

Overview

This server implements the MCP protocol to expose ClickUp functionality as tools that can be called by MCP-compatible clients. It supports retrieving, creating, updating, and getting details of tasks in ClickUp lists.

Origin

This MCP server implementation originated from the need to connect KiloCode with ClickUp, enabling seamless integration between the AI-powered code assistant and ClickUp's task management platform.

Features

• Task Management: Get, create, and update ClickUp tasks
• List Integration: Work with specific ClickUp lists
• MCP Compliant: Full MCP protocol implementation using the official SDK
• TypeScript: Written in TypeScript for type safety

Installation

1. Clone or download this repository
2. Install dependencies:

   npm install
   

3. Build the project:

   npm run build
   

Configuration

Environment Variables

Set the following environment variable before running the server:

• CLICKUP_ACCESS_TOKEN: Your ClickUp API access token. You can generate this from your ClickUp account settings under "Apps" > "API Token".

Example:

export CLICKUP_ACCESS_TOKEN=your_clickup_token_here

Usage

Running the Server

After building, run the server:

node build/index.js

The server communicates via stdio (standard input/output), making it suitable for integration with MCP clients.

Client Integration

MCP clients connect to this server and can call the available tools. The server uses JSON-RPC 2.0 protocol for communication.

Client Configuration

To connect an MCP client to this server, configure the client with the server's command and environment variables.

For example, in Claude Desktop, add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "clickup": {
      "command": "node",
      "args": ["path/to/clickup-mcp-server/build/index.js"],
      "env": {
        "CLICKUP_ACCESS_TOKEN": "your_clickup_token_here"
      }
    }
  }
}

Replace path/to/clickup-mcp-server with the actual path to this project directory.

Tool: get_tasks

Retrieves a list of tasks from a ClickUp list.

Parameters:

• list_id (string, required): The ClickUp List ID
• limit (number, optional): Number of tasks to retrieve (max 100, default 50)

Example Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_tasks",
    "arguments": {
      "list_id": "987654321",
      "limit": 25
    }
  }
}

Example Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "[{\"id\": \"abc123\", \"name\": \"Sample Task\", \"status\": \"open\", \"assignees\": [], \"due_date\": null}, ...]"
      }
    ]
  }
}

Tool: create_task

Creates a new task in a ClickUp list.

Parameters:

• list_id (string, required): The ClickUp List ID
• name (string, required): Task name
• description (string, optional): Task description
• assignees (array of numbers, optional): Array of assignee user IDs
• due_date (string, optional): Due date as Unix timestamp in milliseconds

Example Request:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "create_task",
    "arguments": {
      "list_id": "987654321",
      "name": "New Task",
      "description": "Task description",
      "due_date": "1640995200000"
    }
  }
}

Tool: update_task

Updates an existing ClickUp task.

Parameters:

• task_id (string, required): The ClickUp Task ID
• name (string, optional): New task name
• description (string, optional): New task description
• status (string, optional): New status
• assignees (array of numbers, optional): New array of assignee user IDs
• due_date (string, optional): New due date as Unix timestamp in milliseconds

Example Request:

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "update_task",
    "arguments": {
      "task_id": "abc123",
      "status": "in progress"
    }
  }
}

Tool: get_task

Retrieves details of a specific ClickUp task.

Parameters:

• task_id (string, required): The ClickUp Task ID

Example Request:

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "get_task",
    "arguments": {
      "task_id": "abc123"
    }
  }
}

Finding ClickUp IDs

• List ID: In ClickUp, navigate to your list. The URL will be something like https://app.clickup.com/1234567/v/li/987654321. The number after /li/ is the list ID.
• Task ID: Task URLs contain the task ID, or you can get it from the API responses.
• User IDs: Use ClickUp's API or interface to find user IDs for assignees.

Error Handling

If an API call fails, the response will include an isError: true field with the error message:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "ClickUp API error: Invalid list ID"
      }
    ],
    "isError": true
  }
}

Testing

A test script is provided to verify that the MCP server is working correctly.

1. Set your ClickUp access token:

   export CLICKUP_ACCESS_TOKEN=your_clickup_token_here
   

2. Run the test with a valid list ID:

   node test-mcp.js <list_id>
   

   Replace <list_id> with a valid ClickUp list ID (e.g., 901110500007).

The test will:

• Verify that the server initializes correctly
• Check that all tools are available
• Test the get_tasks tool with the provided list ID

For more comprehensive testing of other tools, you can modify test-mcp.js to include calls to create_task, update_task, and get_task. Note that create_task will create real tasks in ClickUp, so use with caution.

Development

To run in development mode with TypeScript watching:

npm run dev

Dependencies

• @modelcontextprotocol/sdk: MCP protocol implementation
• axios: HTTP client for ClickUp API
• zod: Schema validation
• typescript: TypeScript compiler

License

This project is open source. Please check the license file for details.