Clickup Server

Model Context Protocol server for integrating ClickUp with OpenCode, Antigravity (Google IDE), or any MCP-compatible client. Create tasks, query workspaces, assign modules, and manage your project workflow using natural language commands.

---

Table of Contents

• Capabilities
• Installation
• Usage
• Updating
• Configuration
• API Key
• Per-Project Configuration
• Available Tools
• Development
• Troubleshooting
• License

---

Capabilities

Action	Example Command
Browse workspaces	"Show me my ClickUp workspaces"
Explore lists	"What lists are in my space?"
View statuses	"What statuses does the SIGESP list have?"
View modules	"What modules are available?"
View team members	"Who are the members of this workspace?"
Create tasks	"Create a high-priority task in SIGESP called 'Review pending items' with module TESORERIA"
Update tasks	"Change task 86cad8gv7 to completed with high priority"
Assign tasks	"Assign task 86cad8gv7 to Luis Sanchez"
Create subtasks	"Add a subtask to task 86cacpvg1"
Add comments	"Add a comment to the task saying I already reviewed it"
Delete tasks	"Delete the test task"
List tasks	"Show me the pending tasks in SIGESP"

---

Installation

Run this in any project directory:

npx mcp-clickup-server setup

The setup script will:

1. Prompt for your ClickUp API key
2. Save the key to the global configuration
3. Detect your IDE (OpenCode, Antigravity) and register the server
4. Optionally associate the current project with a ClickUp list

After installation, restart your IDE. The ClickUp tools will be available immediately.

---

Usage

Once installed, you can interact with ClickUp using natural language. The assistant will use the tools automatically based on your request.

Examples:

• "Show me my workspaces"
• "Who are the members of this workspace?"
• "Create a task in SIGESP called 'Review Q3 budget' assigned to Luis"
• "What tasks are pending in this project?"
• "Add a comment to task 86cad8gv7 saying I reviewed it"

If a project has been configured with a ClickUp list, you can omit the list name and the assistant will use the configured list automatically.

---

Updating

To update to the latest version without losing your configuration:

npx mcp-clickup-server update

This preserves your API key and per-project settings. If you installed via git, it pulls the latest code, installs dependencies, and rebuilds.

Reconfigure a project

To change which ClickUp list is associated with the current project:

npx mcp-clickup-server reconfigure

This skips the API key and dependency steps and goes directly to the project configuration wizard.

---

Configuration

Automatic Configuration

The npx mcp-clickup-server setup command automatically detects and configures supported IDEs. No manual steps are required.

Manual Configuration

If automatic detection fails, add the following configuration manually.

For OpenCode:

In ~/.config/opencode/opencode.json:

{
  "mcp": {
    "clickup": {
      "command": ["node", "/path/to/MCP-CLICKUP/dist/index.js"],
      "type": "local"
    }
  }
}

For Antigravity (Google IDE):

In ~/.gemini/config/mcp_config.json:

{
  "mcpServers": {
    "clickup": {
      "command": "node",
      "args": ["/path/to/MCP-CLICKUP/dist/index.js"]
    }
  }
}

---

API Key

A ClickUp Personal API Token is required. Generate one at:

Settings > Apps > API Token or directly at https://app.clickup.com/settings/apps

The token begins with pk_. The server resolves the API key in the following priority order:

1. CLICKUP_API_KEY environment variable
2. Global configuration file at ~/.config/mcp-clickup-server/.env
3. Local .env file in the project directory

---

Per-Project Configuration

Each project can be associated with a specific ClickUp list, allowing the assistant to know where to create tasks without being told every time.

Setup

Run this in your project directory:

npx mcp-clickup-server setup

During setup, you will be prompted to configure the current project. You can:

1. Paste a ClickUp list URL - The setup parses the URL and extracts the list and workspace IDs.
2. Browse workspaces interactively - Select from your workspaces, spaces, and lists.
3. Enter a list ID manually - If you already know the ID.
4. Skip - Configure later.

To change the configuration later, run:

npx mcp-clickup-server reconfigure

Manual Configuration

Create a .mcp-clickup.json file in your project root:

{
  "project": "My Project",
  "listId": "901513520682",
  "listName": "SIGESP",
  "workspaceId": "90151439364",
  "workspaceName": "Ing. Aron Rojas."
}

How It Works

When you ask the assistant to create a task or list tasks without specifying a list, the server checks for .mcp-clickup.json in the current project directory. If found, it uses the configured list automatically.

---

Available Tools

The server exposes 16 tools for ClickUp interaction:

Tool	Description
get_workspaces	List all accessible workspaces
get_workspace_members	List members with IDs, names, and roles
get_authenticated_user	Get the current user's info (ID, name, email)
get_spaces	List spaces within a workspace
get_folders	List folders within a space
get_lists	List lists within a space or folder
get_list_statuses	View available statuses for a list
get_custom_fields	View custom fields (e.g., MODULE dropdown)
get_tasks	List tasks with optional filters (includes assignees)
get_task	Get detailed task information (includes assignees)
get_task_comments	View comments on a task
get_project_config	Get the project's associated ClickUp list
create_task	Create a complete task with all fields
update_task	Update an existing task
add_comment	Add a comment to a task
delete_task	Delete a task

create_task Parameters

Parameter	Type	Required	Description
listId	string	No*	ClickUp list ID (falls back to project config)
name	string	Yes	Task title
description	string	No	Markdown-supported description
status	string	No	Initial status (e.g., "pendiente", "en curso")
priority	number	No	1 (Urgent), 2 (High), 3 (Normal), 4 (Low)
dueDate	string	No	ISO date string or millisecond timestamp
startDate	string	No	Start date (ISO or timestamp)
tags	string[]	No	Tags for the task
assignees	number[]	No	User IDs to assign (use get_workspace_members to find IDs)
parent	string	No	Parent task ID for subtasks
customFields	array	No	Custom field values (e.g., module assignments)

*listId is optional if the project has a .mcp-clickup.json configuration.

---

Development

npm run dev               # Development mode with hot reload
npm run build             # Compile TypeScript
npm start                 # Production mode
npm run update            # Update from git (preserves config)

---

Troubleshooting

"CLICKUP_API_KEY not found" Run npx mcp-clickup-server setup to configure the API key.

ClickUp tools not appearing in IDE after setup Restart your IDE (OpenCode or Antigravity). Verify the configuration file has the correct format.

Error: "Value must be an option index or uuid" Use the get_custom_fields tool to retrieve the available option UUIDs for dropdown fields. Pass the option UUID (not the display name) in the customFields parameter.

Server fails to start Ensure Node.js v20 or later is installed. Run npm run build to verify the TypeScript compiles successfully. Confirm that dist/index.js exists.

---

License

MIT