README.md•6.45 kB
# 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:
```bash
npm install
```
3. Build the project:
```bash
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:
```bash
export CLICKUP_ACCESS_TOKEN=your_clickup_token_here
```
## Usage
### Running the Server
After building, run the server:
```bash
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`:
```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:**
```json
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "get_tasks",
"arguments": {
"list_id": "987654321",
"limit": 25
}
}
}
```
**Example Response:**
```json
{
"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:**
```json
{
"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:**
```json
{
"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:**
```json
{
"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:
```json
{
"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:
```bash
export CLICKUP_ACCESS_TOKEN=your_clickup_token_here
```
2. Run the test with a valid list ID:
```bash
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:
```bash
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.