# 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.