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:
- Log in to ClickUp at https://app.clickup.com
- Navigate to Settings:
- Click your avatar/profile picture in the bottom left corner
- Select "Settings" from the dropdown menu
- Go to Apps section:
- In the left sidebar, click "Apps"
- Then click "API" (or go directly to https://app.clickup.com/settings/apps)
- Generate API Token:
- Click the "Generate" button to create a new personal API token
- Important: This token will only be shown once!
- 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:
- Open Command Palette (
Ctrl+Shift+P/Cmd+Shift+P) - Run "Preferences: Open User Settings (JSON)"
- 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:
- Install "Copilot MCP" from VS Code Marketplace
- Search, manage, and install MCP servers directly from VS Code
- The extension will help you configure the ClickUp MCP server
Cline (AI Coding Assistant):
- Install "Cline" extension for advanced AI coding with MCP support
- Configure ClickUp MCP server through Cline's settings
Managing MCP Servers in VS Code
- Open Command Palette (
Ctrl+Shift+P/Cmd+Shift+P) - Run "MCP: List Servers" to view configured servers
- Select ClickUp server to Start/Stop/Restart or view logs
- Use "MCP: Show Output" for debugging
Verify VS Code Setup
- Ensure your ClickUp API key is configured:
uvx clickup-mcp set-api-key YOUR_KEY - In VS Code, ask GitHub Copilot: "Can you list my ClickUp spaces using MCP tools?"
- Check MCP server status with Command Palette → "MCP: List Servers"
Available Tools (28 Tools)
📝 Task Management
create_task- Create new tasksget_task- Get task details (supports various ID formats)update_task- Update task propertiesdelete_task- Delete taskscreate_task_from_template- Create from predefined templatescreate_task_chain- Create dependent task sequences
🔍 Task Discovery
list_tasks- List tasks with filtering optionssearch_tasks- Search tasks by text and criteriaget_subtasks- Get all subtasks of a parentget_task_comments- Get comments on taskscreate_task_comment- Create comments on tasks
👥 Assignment & Status
get_task_status- Get current task statusupdate_task_status- Change task statusget_assignees- List task assigneesassign_task- Assign users to tasks
🗂️ Navigation
list_spaces- List all spaces in workspacelist_folders- List folders in a spacelist_lists- List all listsfind_list_by_name- Find lists by name
⚡ Bulk Operations
bulk_update_tasks- Update multiple tasks at oncebulk_move_tasks- Move multiple tasks to different lists
⏱️ Time Tracking
get_time_tracked- Get time tracked for users/periodslog_time- Log time spent on tasks
📊 Analytics
get_team_workload- See task distribution across team membersget_task_analytics- Get velocity metrics and completion rates
👤 User Management
list_users- List all users in workspaceget_current_user- Get current authenticated user detailsfind_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
- Fork the repository
- Create a feature branch (
git checkout -b feature/improvement) - Make changes and add tests
- Ensure all tests pass (
uv run pytest) - Run linting (
uv run ruff check .) - 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