ClickUp MCP Server

A Model Context Protocol (MCP) server that enables Claude Desktop to interact with ClickUp through natural language commands.

Features

• User Management: Get current user profile and verify authentication
• Task Management: Complete CRUD operations - get, create, update, delete tasks
• Task Listing: List and filter tasks with pagination
• Natural Language: Ask Claude to manage your ClickUp workspace in plain English

Quick Start

1. Install: python -m pip install -e .
2. Configure: Add to Claude Desktop config with your CLICKUP_API_TOKEN
3. Test: Ask Claude "Use the clickup server to get my user profile"
4. Create: "Create a task named 'Test Task' in list LIST_ID"

Installation

Prerequisites

• Python 3.10 or higher
• ClickUp API token (get one here)

Local Development

1. Clone the repository:

git clone https://github.com/deniskrds/clickup-mcp-server.git
cd clickup-mcp-server

2. Create a virtual environment:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install the package:

python -m pip install -e .

4. Create environment file:

cp .env.example .env
# Edit .env and add your CLICKUP_API_TOKEN

Claude Desktop Setup

1. Open Claude Desktop configuration:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json

2. Add the MCP server configuration:

{
  "mcpServers": {
    "clickup": {
      "command": "clickup-mcp",
      "env": {
        "CLICKUP_API_TOKEN": "your_token_here"
      }
    }
  }
}

3. Restart Claude Desktop

Usage

Once configured, you can ask Claude to manage your ClickUp workspace:

User & Authentication

• "Use the clickup server to get my user profile"
• "Verify my ClickUp authentication"

Task Management

• "Use the clickup server to create a task named 'Review PR' in list LIST_ID"
• "Update task TASK_ID: set status to 'In Progress'"
• "List tasks in list LIST_ID with status 'Open'"
• "Get task TASK_ID details"
• "Delete task TASK_ID"

Example Workflow

1. Create task: "Use the clickup server to create a task named 'Review PR #456' in list LIST_ID"
2. Get task details: "Get task TASK_ID to see the created task"
3. Update task: "Update task TASK_ID: set status to 'In Progress' and assign to user 123"
4. Complete task: "Update task TASK_ID: set status to 'Complete'"

Available Tools

Tool	Description	Parameters
get_user	Get current user profile	None
get_task	Get specific task details	task_id
create_task	Create new task	list_id, name, description, assignees, tags, status, priority, due_date
update_task	Update existing task	task_id, name, description, assignees, tags, status, priority, due_date
delete_task	Delete a task	task_id
list_tasks	List tasks in a list	list_id, page, limit, status, assignees

Configuration

The server uses environment variables for configuration:

# Required
CLICKUP_API_TOKEN=your_clickup_token

# Optional (defaults shown)
CLICKUP_APP_ENV=development
CLICKUP_BASE_URL=https://api.clickup.com/api/v2
CLICKUP_REQUEST_TIMEOUT_SECONDS=15
CLICKUP_MAX_RETRIES=2
CLICKUP_RETRY_BACKOFF_SECONDS=0.5

Development

Project Structure

clickup_mcp/
├── clickup/          # ClickUp API client
├── tools/            # Task management tools
├── models.py         # Pydantic models
├── config.py         # Configuration management
└── mcp_server.py     # MCP server entry point

tests/
└── test_mcp_server.py # Unit tests

Adding New Tools

1. Implement helper functions in clickup_mcp/tools/
2. Register tools in clickup_mcp/mcp_server.py
3. Add clear docstrings and parameter types

Troubleshooting

"Server disconnected" error:

• Ensure clickup-mcp command is in your PATH
• Check that CLICKUP_API_TOKEN is set correctly
• Verify Python version is 3.10+

"Module not found" errors:

• Reinstall the package: python -m pip install -e .
• Activate your virtual environment

Claude can't find the server:

• Use absolute path in Claude config: /full/path/to/venv/bin/clickup-mcp
• Restart Claude Desktop after config changes

License

This project is licensed under the MIT License. See the LICENSE file for details.

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

Contact

For questions or support, please open an issue on GitHub.