@d4works/mcp-clickup

MCP (Model Context Protocol) server for ClickUp task management. Allows Claude to read task details from ClickUp and help with implementation.

Features

• Fetch task details (description, comments, attachments, custom fields, etc.)
• Support for multiple task ID formats (URL, custom ID, number)
• Instructions for Claude to analyze tasks before implementation

Configuration

1. Environment Variables

| Variable | Required | Description | | --------------------- | -------- | ------------------------------------------------ | | CLICKUP_API_TOKEN | Yes | Your ClickUp API token | | CLICKUP_TEAM_ID | Yes | Your ClickUp team/workspace ID | | CLICKUP_TASK_PREFIX | No | Task prefix for number-only input (e.g., "PROJ") |

2. Get Your API Token

1. Open ClickUp → Click your avatar → Settings
2. Go to Apps section
3. Generate or copy your API Token

3. Find Your Team ID

1. Open ClickUp → Go to any workspace
2. Look at the URL: https://app.clickup.com/{TEAM_ID}/...
3. The number in the URL is your Team ID

4. Create MCP Configuration

Create .mcp.json in your project root.

First, store your API token in a local file that's gitignored:

echo "export CLICKUP_API_TOKEN=pk_your_token_here" >> .claude/.env.local

Then configure .mcp.json to source this file before running the server:

{
  "mcpServers": {
    "clickup": {
      "command": "bash",
      "args": [
        "-c",
        "export $(cat .claude/.env.local | xargs) && npx -y @d4works/mcp-clickup"
      ],
      "env": {
        "CLICKUP_TEAM_ID": "your_team_id",
        "CLICKUP_TASK_PREFIX": "PROJ"
      }
    }
  }
}

Note: If you have CLICKUP_API_TOKEN exported in your global ~/.zshrc or ~/.bashrc, you can simplify the command to just npx -y @d4works/mcp-clickup.

Usage

Ask Claude to work on a task using any of these formats:

> Work on task ABC-123
> Work on task 123
> Work on task https://app.clickup.com/t/12345/ABC-123

Claude will:

1. Fetch task details from ClickUp
2. Analyze the task (description, comments, attachments)
3. Propose an implementation plan
4. Wait for your approval before writing code

Available Tools

test-connection

Test connection to ClickUp API.

get-task

Get task details from ClickUp (description, status, comments, attachments, custom fields, checklists, etc.).

Parameters:

• taskId (string, required): Task URL, custom ID (ABC-123), or number

get-task-statuses

Get available statuses for a task. Use this before updating status to see valid options.

Parameters:

• taskId (string, required): Task URL, custom ID (ABC-123), or number

set-task-status

Set the status of a ClickUp task. Only used with explicit user confirmation.

Parameters:

• taskId (string, required): Task URL, custom ID (ABC-123), or number
• status (string, required): New status name (must match one of the available statuses)

get-release-options

Get available Release dropdown options for a task. Use this to see valid values before setting Release.

Parameters:

• taskId (string, required): Task URL, custom ID (ABC-123), or number
• fieldName (string, optional): Name of the dropdown field (default: "Release")

set-task-release

Set the Release dropdown value on a ClickUp task. Only used with explicit user confirmation.

Parameters:

• taskId (string, required): Task URL, custom ID (ABC-123), or number
• release (string, required): Release value to set (must match one of the available options)
• fieldName (string, optional): Name of the dropdown field (default: "Release")

License

MIT