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

1. Clone this repository:

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

2. Install dependencies:

npm install

3. Build the project:

npm run build

4. Get your credentials:

   • ClickUp API key from ClickUp Settings
   • 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:

{
  "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.