ClickUp MCP

# 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` ```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](https://app.clickup.com/settings/apps) - 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 1. Clone this repository: ```bash git clone https://github.com/TwoFeetUp/clickup-mcp.git cd clickup-mcp ``` 2. Install dependencies: ```bash npm install ``` 3. Build the project: ```bash npm run build ``` 4. Get your credentials: - ClickUp API key from [ClickUp Settings](https://app.clickup.com/settings/apps) - Team ID from your ClickUp workspace URL 5. Configure your MCP client (e.g., Claude Desktop): Add this entry to your client's MCP settings JSON file: ```json { "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 ```bash # 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](MCP_DESIGN_PRINCIPLES.md) for detailed design philosophy. ## License MIT ## Credits This optimized version builds upon the original [ClickUp MCP Server](https://github.com/TaazKareem/clickup-mcp-server) by Talib Kareem, with significant architectural improvements and performance optimizations. Optimizations by Sjoerd Tiemensma.