ClickUp MCP - Optimized AI Integration
A high-performance Model Context Protocol (MCP) server for integrating ClickUp with AI applications. This optimized fork features consolidated tools, response optimization, and intelligent caching for superior performance.
🚀 Key Optimizations
This repository builds on the original ClickUp MCP server with significant performance and efficiency improvements:
- Tool Consolidation: Reduced from 36 tools to 15 consolidated, action-based tools following MCP design principles
- Response Optimization: 54% token reduction through intelligent field filtering and data flattening
- Intelligent Caching: 15-minute TTL workspace hierarchy cache with 85% performance improvement
- Hybrid Lookups: Direct API calls when IDs available, fallback to cached hierarchy when needed
- AI-First Design: Tools designed around user intent rather than API structure
Performance Results
| Operation | Before | After | Improvement |
|---|---|---|---|
| Response tokens (7 tasks) | 723 | 331 | 54% reduction |
| Workspace lookup (warm) | 2400ms | 350ms | 85% faster |
| Task search (cached) | 3000ms | 350ms | 88% faster |
Requirements
- Node.js v18.0.0 or higher (required for MCP SDK compatibility)
- ClickUp API key and Team ID
Installation
Quick Start (Recommended)
Add this to your Claude Desktop config file:
Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
{
"mcpServers": {
"ClickUp": {
"command": "npx",
"args": [
"-y",
"@twofeetup/clickup-mcp@latest"
],
"env": {
"CLICKUP_API_KEY": "your-api-key-here",
"CLICKUP_TEAM_ID": "your-team-id-here"
}
}
}
}
Get your credentials:
- ClickUp API key: ClickUp Settings
- Team ID: Found in your ClickUp workspace URL
Restart Claude Desktop and the server will be automatically installed and ready to use!
Local Development Setup
- Clone this repository:
git clone https://github.com/TwoFeetUp/clickup-mcp.git
cd clickup-mcp
- Install dependencies:
npm install
- Build the project:
npm run build
-
Get your credentials:
- ClickUp API key from ClickUp Settings
- Team ID from your ClickUp workspace URL
-
Configure your MCP client (e.g., Claude Desktop):
Add this entry to your client's MCP settings JSON file:
{
"mcpServers": {
"ClickUp": {
"command": "node",
"args": [
"/path/to/clickup-mcp/build/index.js"
],
"env": {
"CLICKUP_API_KEY": "your-api-key",
"CLICKUP_TEAM_ID": "your-team-id"
}
}
}
}
Consolidated Tools
This server provides 15 consolidated tools instead of the original 36:
Task Management
- manage_task: Create, update, delete, move, or duplicate tasks with action-based routing
- search_tasks: Find tasks by ID, list, or workspace-wide filters with configurable detail levels
- task_comments: Get or create task comments
- task_time_tracking: Manage time entries (get, start, stop, add, delete)
- attach_file_to_task: Attach files to tasks
Container Management
- manage_container: Create, update, delete, or get lists and folders
- get_container: Retrieve container details
Document Management
- manage_document: Create, update, delete documents
- manage_document_page: Create, update, delete document pages
- list_documents: List all documents in workspace
Organization
- find_members: Search workspace members by name/email
- operate_tags: Create, update, delete, or list tags
Bulk Operations
- bulk_create_tasks: Create multiple tasks efficiently
- bulk_update_tasks: Update multiple tasks at once
- bulk_delete_tasks: Delete multiple tasks in one operation
Key Features
AI-First Tool Design
- Tools organized by user intent, not API structure
- Natural language parameter names
- Support for flexible task identification (ID, name, or custom ID)
- Detail level control (minimal, standard, detailed)
Response Optimization
- Automatic field filtering and null removal
- Nested object flattening (status → string, assignees → usernames)
- Configurable detail levels for token efficiency
- Pagination support for large result sets
Performance Features
- 15-minute TTL workspace hierarchy cache
- Direct API lookups when IDs provided
- Graceful fallback to cached hierarchy
- Automatic cache invalidation
- Rate limit awareness (600ms spacing)
Developer Experience
- Comprehensive TypeScript types
- Detailed logging with operation tracking
- Consistent error handling
- Input validation with helpful messages
Configuration
Environment variables:
CLICKUP_API_KEY: Your ClickUp API key (required)CLICKUP_TEAM_ID: Your ClickUp team/workspace ID (required)LOG_LEVEL: Logging verbosity (default: "info")
Development
# Install dependencies
npm install
# Build
npm run build
# Watch mode (for development)
npm run dev
# Run tests
node test-cache-performance.js
node test-optimized-response.js
Architecture
This server follows MCP design principles:
- Tool Consolidation: Related operations grouped into single tools with action parameters
- Token Efficiency: Optimized response formats with field selection and detail levels
- Performance: Intelligent caching and direct API fallbacks
- Maintainability: Clear separation of concerns, consistent patterns
See MCP_DESIGN_PRINCIPLES.md for detailed design philosophy.
License
MIT
Credits
This optimized version builds upon the original ClickUp MCP Server by Talib Kareem, with significant architectural improvements and performance optimizations.
Optimizations by Sjoerd Tiemensma.