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
- Clone or download this repository
- Install dependencies:
npm install - 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 IDlimit(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 IDname(string, required): Task namedescription(string, optional): Task descriptionassignees(array of numbers, optional): Array of assignee user IDsdue_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 IDname(string, optional): New task namedescription(string, optional): New task descriptionstatus(string, optional): New statusassignees(array of numbers, optional): New array of assignee user IDsdue_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.
-
Set your ClickUp access token:
export CLICKUP_ACCESS_TOKEN=your_clickup_token_here -
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_taskstool 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 implementationaxios: HTTP client for ClickUp APIzod: Schema validationtypescript: TypeScript compiler
License
This project is open source. Please check the license file for details.