ClickUp MCP Server

A Model Context Protocol (MCP) server that enables AI assistants to interact with ClickUp's task management API. This server provides comprehensive task management capabilities through natural language, focusing on essential project workflows rather than ClickUp's full feature set.

Built by the Diversio team for streamlined AI-powered task management.

🚀 What This Server Provides

✅ Core Task Management

• Task CRUD Operations - Create, read, update, and delete tasks
• Task Organization - Navigate spaces, folders, and lists
• Task Search & Filtering - Find tasks by various criteria
• Comments & Collaboration - Read and create comments on tasks
• User & Assignment Management - List users, find by name/email, assign to tasks
• Status Management - Update and track task statuses

✅ Productivity Features

• Bulk Operations - Update or move multiple tasks at once
• Time Tracking - Log time and view tracked hours
• Task Templates - Create tasks from predefined templates (bug report, feature request, code review)
• Task Chains - Create sequences of dependent tasks
• Team Analytics - View workload distribution and completion metrics

✅ Flexible ID Support

• Standard ClickUp IDs (abc123)
• Custom ID patterns (gh-123, bug-456)
• ClickUp URLs (https://app.clickup.com/t/abc123)
• Hash format (#123)

❌ What's NOT Included

This server focuses on task management essentials. Not supported:

• ClickUp Docs/Documents
• Whiteboards
• Dashboards
• Automations/Workflows
• Goals/Targets
• File/Attachment management
• Webhook management
• Advanced custom field operations
• Calendar views
• Forms integration

API Coverage: ~30-40% of ClickUp's full API, covering the most common task management workflows.

Installation

Quick Start (Recommended)

# Install from GitHub (latest)
uvx --from git+https://github.com/DiversioTeam/clickup-mcp clickup-mcp

# Or from PyPI (when published)
uvx clickup-mcp

Development Installation

git clone https://github.com/DiversioTeam/clickup-mcp
cd clickup-mcp
uv sync
uv run clickup-mcp

Configuration

API Key Setup

# Set your ClickUp API key
uvx clickup-mcp set-api-key YOUR_API_KEY_HERE

# Or set environment variable
export CLICKUP_MCP_API_KEY=your_api_key

Getting Your ClickUp API Key

Step-by-step instructions:

1. Log in to ClickUp at https://app.clickup.com
2. Navigate to Settings:
   • Click your avatar/profile picture in the bottom left corner
   • Select "Settings" from the dropdown menu
3. Go to Apps section:
   • In the left sidebar, click "Apps"
   • Then click "API" (or go directly to https://app.clickup.com/settings/apps)
4. Generate API Token:
   • Click the "Generate" button to create a new personal API token
   • Important: This token will only be shown once!
5. Copy and Save:
   • Copy the generated token immediately
   • Store it securely (password manager recommended)
   • Configure it using: uvx clickup-mcp set-api-key YOUR_TOKEN_HERE

Important Notes:

• Personal API tokens have the same permissions as your user account
• Keep your token secure - treat it like a password
• If you lose the token, you'll need to regenerate a new one
• Tokens don't expire but can be revoked in the same settings page

Usage with AI Assistants

Claude Code (CLI)

Add to ~/.config/claude-code/mcp-settings.json:

{
  "servers": {
    "clickup": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/DiversioTeam/clickup-mcp.git", "clickup-mcp"]
    }
  }
}

Claude Desktop

Add to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json Linux: ~/.config/claude/claude_desktop_config.json

{
  "mcpServers": {
    "clickup": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/DiversioTeam/clickup-mcp.git", "clickup-mcp"]
    }
  }
}

VS Code

VS Code has excellent MCP support through both native integration and extensions. Multiple setup options available:

Option 1: Native VS Code MCP (Recommended)

VS Code now has built-in MCP support with GitHub Copilot and Agent Mode. Add to your workspace:

Create .vscode/mcp.json in your project:

{
  "servers": {
    "clickup": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/DiversioTeam/clickup-mcp.git", "clickup-mcp"]
    }
  }
}

Or add to VS Code User Settings:

1. Open Command Palette (Ctrl+Shift+P / Cmd+Shift+P)
2. Run "Preferences: Open User Settings (JSON)"
3. Add to settings:

{
  "mcp": {
    "servers": {
      "clickup": {
        "command": "uvx",
        "args": ["--from", "git+https://github.com/DiversioTeam/clickup-mcp.git", "clickup-mcp"]
      }
    }
  }
}

Option 2: VS Code Extensions with MCP Support

Copilot MCP Extension:

1. Install "Copilot MCP" from VS Code Marketplace
2. Search, manage, and install MCP servers directly from VS Code
3. The extension will help you configure the ClickUp MCP server

Cline (AI Coding Assistant):

1. Install "Cline" extension for advanced AI coding with MCP support
2. Configure ClickUp MCP server through Cline's settings

Managing MCP Servers in VS Code

1. Open Command Palette (Ctrl+Shift+P / Cmd+Shift+P)
2. Run "MCP: List Servers" to view configured servers
3. Select ClickUp server to Start/Stop/Restart or view logs
4. Use "MCP: Show Output" for debugging

Verify VS Code Setup

1. Ensure your ClickUp API key is configured: uvx clickup-mcp set-api-key YOUR_KEY
2. In VS Code, ask GitHub Copilot: "Can you list my ClickUp spaces using MCP tools?"
3. Check MCP server status with Command Palette → "MCP: List Servers"

Available Tools (28 Tools)

📝 Task Management

• create_task - Create new tasks
• get_task - Get task details (supports various ID formats)
• update_task - Update task properties
• delete_task - Delete tasks
• create_task_from_template - Create from predefined templates
• create_task_chain - Create dependent task sequences

🔍 Task Discovery

• list_tasks - List tasks with filtering options
• search_tasks - Search tasks by text and criteria
• get_subtasks - Get all subtasks of a parent
• get_task_comments - Get comments on tasks
• create_task_comment - Create comments on tasks

👥 Assignment & Status

• get_task_status - Get current task status
• update_task_status - Change task status
• get_assignees - List task assignees
• assign_task - Assign users to tasks

🗂️ Navigation

• list_spaces - List all spaces in workspace
• list_folders - List folders in a space
• list_lists - List all lists
• find_list_by_name - Find lists by name

⚡ Bulk Operations

• bulk_update_tasks - Update multiple tasks at once
• bulk_move_tasks - Move multiple tasks to different lists

⏱️ Time Tracking

• get_time_tracked - Get time tracked for users/periods
• log_time - Log time spent on tasks

📊 Analytics

• get_team_workload - See task distribution across team members
• get_task_analytics - Get velocity metrics and completion rates

👤 User Management

• list_users - List all users in workspace
• get_current_user - Get current authenticated user details
• find_user_by_name - Find users by name or email

Example Usage

Natural Language Commands

Ask your AI assistant:

"Create a bug report for login issues in the Development list"
"Show me all high-priority tasks assigned to me"
"Move all completed tasks from Sprint 1 to Archive"
"Log 2 hours on task gh-123 for debugging"
"What's our team's current workload?"
"Create a task chain: Design → Implement → Test → Deploy"
"Add a comment to task GH-3761 saying 'testing complete'"
"Get all comments on the bug report task"
"Comment on task abc123 and assign it to John"

Task Templates

"Create a bug report template for the payment processing issue"
"Use the code review template for PR #456"
"Create a feature request for dark mode"

Analytics Queries

"What's our task completion rate this month?"
"Who has the most tasks assigned?"
"Show me time tracked on the API project"

Development

Running Tests

# Run all tests (62 tests)
uv run pytest

# Run with coverage
uv run pytest --cov=clickup_mcp

# Run specific test
uv run pytest tests/test_client.py::test_create_task

Code Quality

# Check code style
uv run ruff check .

# Format code
uv run ruff format .

# Type checking
uv run mypy src/

Troubleshooting

Check Configuration

# Verify API key is configured
uv run clickup-mcp check-config

# Test API connection
uv run clickup-mcp test-connection

Debug Mode

# Run with debug logging
uv run clickup-mcp --debug

Local Testing with Claude Code

# Add the server for local testing with Claude Code CLI
claude mcp add clickup-local -- uv run clickup-mcp

# Then you can test the functionality immediately
# Example: List spaces, create tasks, add comments, etc.

Technical Limitations

• Rate Limiting: No built-in rate limiting (ClickUp: 100 req/min)
• Pagination: Limited pagination support
• Caching: No response caching implemented
• Custom Fields: Models exist but limited tool support
• Error Recovery: Basic error handling without sophisticated retry

Contributing

We welcome contributions! Focus areas:

Priority Improvements

• Enhanced error handling and retry logic
• Response caching implementation
• Better pagination support
• Expanded custom field support

How to Contribute

1. Fork the repository
2. Create a feature branch (git checkout -b feature/improvement)
3. Make changes and add tests
4. Ensure all tests pass (uv run pytest)
5. Run linting (uv run ruff check .)
6. Submit a Pull Request

Development Setup

git clone https://github.com/yourusername/clickup-mcp
cd clickup-mcp
uv sync
uv run pytest  # Ensure tests pass

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: tech@diversio.com

License

MIT License - see LICENSE file for details.

Acknowledgments

• Built by Diversio team
• Powered by Model Context Protocol
• Uses ClickUp API v2