ClickUp MCP Server

A Model Context Protocol (MCP) server that provides tools for interacting with the ClickUp API. This server allows AI assistants to manage ClickUp workspaces, teams, spaces, lists, and tasks.

✅ Project Status

The ClickUp MCP Server has been successfully created and is ready for use!

Key Features Implemented:

• ✅ Full TypeScript implementation with ES modules
• ✅ Complete ClickUp API integration (v2)
• ✅ 29 powerful MCP tools with full CRUD operations
• ✅ Complete workspace management: Teams, Spaces, Folders, Lists, Tasks
• ✅ Custom Fields support with full CRUD operations
• ✅ Remote support via HTTP/SSE transport
• ✅ Flexible transport modes: stdio and Server-Sent Events (SSE)
• ✅ Enhanced Error Handling & Structured Logging
• ✅ Resilience Patterns (Circuit Breaker, Retry Logic)
• ✅ Comprehensive Monitoring & Health Checks
• ✅ Performance Metrics & Observability
• ✅ Comprehensive testing suite with Jest
• ✅ Comprehensive error handling and validation
• ✅ VS Code integration with tasks and debugging
• ✅ Ready for Claude Desktop integration
• ✅ Web-based health checks and status endpoints
• ✅ CI/CD pipeline with GitHub Actions

Next Steps:

1. Set up your ClickUp API token (see Configuration section below)
2. Build and test the server
3. Configure Claude Desktop (see Usage section)
4. Start managing your ClickUp workspace with AI!

Features

Available Tools

Team & Workspace Management

• get_teams: Get all teams accessible to the authenticated user

Space Management (Full CRUD)

• get_spaces: Get all spaces in a team
• create_space: Create a new space in a team with features configuration
• update_space: Update space properties (name, color, privacy, features)
• delete_space: Delete a space

Folder Management (Full CRUD)

• get_folders: Get all folders in a space
• create_folder: Create a new folder in a space
• update_folder: Update folder name
• delete_folder: Delete a folder

List Management (Full CRUD)

• get_lists: Get all lists in a space (across all folders)
• get_folder_lists: Get all lists in a specific folder
• create_list: Create a new list in a folder with metadata
• update_list: Update list properties (name, content, due date, priority, assignee)
• delete_list: Delete a list

Task Management (Full CRUD)

• get_tasks: Get all tasks in a list (with option to include closed tasks)
• get_task: Get detailed information about a specific task
• create_task: Create a new task in a list with optional parameters (description, priority, assignees, due date, tags)
• update_task: Comprehensive task update with multiple fields
• delete_task: Delete a task

Task Updates (Granular)

• update_task_status: Update the status of an existing task
• update_task_assignees: Add, remove, or set task assignees
• update_task_due_date: Update or remove task due dates
• update_task_priority: Update or remove task priority

Task Comments

• add_task_comment: Add comments to tasks with notification options
• get_task_comments: Retrieve all comments for a task

Custom Fields Management (Full CRUD)

• get_list_custom_fields: Get all custom fields available for a list
• get_task_custom_fields: Get custom field values for a specific task
• update_task_custom_field: Update a single custom field value for a task
• set_task_custom_fields: Set multiple custom field values for a task at once
• create_list_custom_field: Create a new custom field for a list (supports text, number, date, dropdown, checkbox, etc.)
• delete_list_custom_field: Delete a custom field from a list

Setup

Prerequisites

• Node.js 16 or higher
• A ClickUp account with API access
• ClickUp API token

Installation

1. Clone or download this project

2. Install dependencies:

   npm install

3. Build the TypeScript code:

   npm run build

Configuration

Set up your ClickUp API token as an environment variable:

export CLICKUP_API_TOKEN="your_clickup_api_token_here"

You can get your ClickUp API token from:

1. Go to ClickUp
2. Click on your avatar in the bottom left
3. Go to "Settings"
4. Go to "Apps"
5. Generate an API token

Usage

Running the Server

The server supports two transport modes:

1. Stdio Transport (Default - for Claude Desktop)

npm start
# or
node build/index.js

2. Server-Sent Events (SSE) Transport (Remote Access)

# Default SSE mode (localhost:3000)
npm run start:sse

# Development SSE mode (all interfaces, port 3000)
npm run start:sse:dev

# Custom configuration
node build/index.js --transport sse --port 8080 --host 0.0.0.0

3. Development Mode (with file watching)

npm run dev

Transport Modes Explained

• Stdio Transport: Perfect for local development and Claude Desktop integration. Communicates via standard input/output.
• SSE Transport: Enables remote access over HTTP using Server-Sent Events. Ideal for:
  • Remote development environments
  • Cloud deployments
  • Web-based MCP clients
  • Multi-user scenarios

SSE Server Features

When running in SSE mode, the server provides:

• Health Check Endpoint: GET /health - Returns server status
• Metrics Endpoint: GET /metrics - Performance metrics in JSON format
• Status Endpoint: GET /status - Server information and statistics
• MCP SSE Endpoint: GET /sse - MCP protocol over Server-Sent Events
• Status Page: GET / - Enhanced web interface with monitoring links

Monitoring & Observability

The server includes comprehensive monitoring and observability features:

Error Handling

• Custom Error Types: ClickUpAPIError, RateLimitError, AuthenticationError, ValidationError, NetworkError, TimeoutError
• Structured Error Responses: Consistent error format with correlation IDs
• Error Recovery: Automatic retry logic and circuit breaker patterns

Logging

• Structured JSON Logging: Configurable log levels (DEBUG, INFO, WARN, ERROR, FATAL)
• Correlation IDs: Request tracing across API calls
• Contextual Information: Rich metadata in all log entries
• Text & JSON Formats: Configurable output formats

Resilience Patterns

• Circuit Breaker: Prevents cascade failures with configurable thresholds
• Retry Logic: Exponential backoff with jitter for failed requests
• Timeout Handling: Configurable request timeouts

Health Checks

• API Token Validation: Ensures ClickUp API token is configured
• Memory Usage Monitoring: Tracks memory utilization with alerts
• System Health: Overall service health status

Metrics Collection

• API Request Metrics: Count, duration, and error rates
• Tool Execution Metrics: Performance tracking for all tools
• System Metrics: Memory usage and active connections
• Circuit Breaker Status: Real-time resilience pattern monitoring

Configuration

Configure logging and monitoring via environment variables:

# Logging Configuration
LOG_LEVEL=INFO          # DEBUG, INFO, WARN, ERROR, FATAL  
LOG_FORMAT=json         # json, text
NO_COLOR=false         # Disable colored output

# Required
CLICKUP_API_TOKEN=your_token_here

For detailed information, see Error Handling and Logging Documentation.

Command Line Options

node build/index.js [options]

Options:
  --transport <type>  Transport type: 'stdio' or 'sse' (default: stdio)
  --port <number>     Port for SSE transport (default: 3000)
  --host <string>     Host for SSE transport (default: localhost)
  --help             Show help message

Examples:
  node build/index.js                                    # stdio transport
  node build/index.js --transport sse                    # SSE on default port
  node build/index.js --transport sse --port 8080        # SSE on port 8080
  node build/index.js --transport sse --host 0.0.0.0     # SSE on all interfaces

Using with Claude Desktop

Stdio Transport (Recommended)

To use this server with Claude Desktop, add the following configuration to your claude_desktop_config.json file:

{
  "mcpServers": {
    "clickup": {
      "command": "node",
      "args": ["/absolute/path/to/clickup-mcp/build/index.js"],
      "env": {
        "CLICKUP_API_TOKEN": "your_clickup_api_token_here"
      }
    }
  }
}

Important: Replace /absolute/path/to/clickup-mcp/ with the actual absolute path to your project directory.

SSE Transport (Remote)

For remote access via SSE transport, configure Claude Desktop to connect to your running server:

{
  "mcpServers": {
    "clickup-remote": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/inspector", "http://your-server:3000/sse"],
      "env": {}
    }
  }
}

Or use a direct SSE connection if your MCP client supports it:

• SSE Endpoint: http://your-server:3000/sse
• Health Check: http://your-server:3000/health

Example Usage

Once connected to an MCP client, you can use commands like:

• "Show me all my ClickUp teams"
• "List the spaces in team 12345"
• "Get all tasks from list 67890"
• "Create a new task called 'Review documentation' in list 67890"
• "Update task 11111 status to 'in progress'"
• "Show me details for task 22222"

Testing Your Setup

To verify your ClickUp MCP server is working correctly:

1. Test API Token:

   export CLICKUP_API_TOKEN="your_token_here"
   npm run test-token

   This should return your ClickUp team information in JSON format.

2. Test Server Startup (Stdio Mode):

   node build/index.js

   You should see: "ClickUp MCP Server running on stdio"

3. Test Server Startup (SSE Mode):

   node build/index.js --transport sse

   You should see: "ClickUp MCP Server running on http://localhost:3000"

4. Test Remote Endpoints:

   # Health check
   curl http://localhost:3000/health
      
   # Server info page
   curl http://localhost:3000/
      
   # Test SSE endpoint (should wait for connections)
   curl -N -H "Accept: text/event-stream" http://localhost:3000/sse

5. Test with MCP Inspector (Optional): If you have the MCP Inspector tool, you can test both transports:

   # Test stdio transport
   npx @modelcontextprotocol/inspector node build/index.js
      
   # Test SSE transport (start server first)
   npm run start:sse &
   npx @modelcontextprotocol/inspector http://localhost:3000/sse

6. Verify Claude Desktop Integration:

   • Add the server to your Claude Desktop config
   • Restart Claude Desktop
   • Look for the ClickUp tools in the tools panel (🔧 icon)

Testing

The project includes a comprehensive testing suite to ensure reliability and maintainability.

Running Tests

# Run all tests
npm test

# Run tests in watch mode (for development)
npm run test:watch

# Run tests with coverage report
npm run test:coverage

# Run specific test types
npm run test:unit         # Unit tests only
npm run test:integration  # Integration tests only

Test Structure

tests/
├── setup.ts              # Global test configuration
├── mocks/                # Mock data and utilities
├── unit/                 # Unit tests for individual components
└── integration/          # Integration tests for HTTP/SSE server

Test Framework

• Jest: Main testing framework with TypeScript support
• Supertest: HTTP endpoint testing
• Coverage: Comprehensive code coverage reporting

Using the Test Runner Script

# Interactive test runner with colored output
./run-tests.sh           # Run all tests
./run-tests.sh unit      # Unit tests only
./run-tests.sh coverage  # Generate coverage report
./run-tests.sh watch     # Watch mode
./run-tests.sh help      # Show usage

VS Code Testing

Access testing tasks via Ctrl+Shift+P → "Tasks: Run Task":

• Run Tests: Execute all tests once
• Run Tests (Watch): Continuous testing during development
• Run Tests (Coverage): Generate detailed coverage reports

For detailed testing information, see TESTING.md.

Development

Project Structure

clickup-mcp/
├── src/
│   └── index.ts          # Main server implementation
├── build/                # Compiled JavaScript (generated)
├── .github/
│   └── copilot-instructions.md
├── .vscode/              # VS Code configuration
│   ├── tasks.json        # Build and run tasks
│   └── mcp.json          # MCP testing configuration
├── Dockerfile            # Container configuration
├── docker-compose.yml    # Docker Compose setup
├── config.env.example    # Environment configuration template
├── package.json
├── tsconfig.json
└── README.md

Building

npm run build

Development Mode

npm run dev

This will start TypeScript in watch mode, automatically recompiling when you make changes.

Clean Build

npm run clean
npm run build

VS Code Integration

This project includes VS Code configuration for easy development:

• Tasks: Use Ctrl+Shift+P → "Tasks: Run Task" to access build/run tasks:
  • "Build ClickUp MCP Server" - Compile TypeScript
  • "Run ClickUp MCP Server" - Start in stdio mode
  • "Run ClickUp MCP Server (SSE)" - Start in SSE mode on localhost:3000
  • "Run ClickUp MCP Server (SSE Dev)" - Start in SSE mode on all interfaces
  • "Development Mode" - Auto-rebuild on changes
• MCP Testing: The .vscode/mcp.json file allows testing the server directly in VS Code
• Development: Use F5 to start debugging or run the "Development Mode" task for auto-rebuilding

API Integration

This server integrates with the ClickUp API v2. Key endpoints used:

• /team - Get teams
• /team/{team_id}/space - Get spaces
• /space/{space_id}/list - Get lists
• /list/{list_id}/task - Get/create tasks
• /task/{task_id} - Get/update specific tasks

Authentication

The server requires a ClickUp API token set as the CLICKUP_API_TOKEN environment variable. The token is used for Bearer authentication with the ClickUp API.

Error Handling

The server includes comprehensive error handling for:

• Missing API tokens
• Failed API requests
• Invalid parameters
• Network issues

Errors are logged to stderr and returned as appropriate MCP responses.

Rate Limiting

The server respects ClickUp's API rate limits. If you encounter rate limiting issues, consider adding delays between requests or reducing the frequency of API calls.

Deployment

Local Deployment

The simplest way to deploy is using the built-in npm scripts:

# Build the project
npm run build

# Run in production mode (stdio)
npm start

# Run in remote mode (SSE)
npm run start:sse

Docker Deployment

For containerized deployment:

1. Build and run with Docker:

   # Build the Docker image
   docker build -t clickup-mcp .
      
   # Run the container
   docker run -d \
     --name clickup-mcp \
     -p 3000:3000 \
     -e CLICKUP_API_TOKEN=your_token_here \
     clickup-mcp

2. Using Docker Compose:

   # Create .env file with your token
   echo "CLICKUP_API_TOKEN=your_token_here" > .env
      
   # Start the service
   docker-compose up -d
      
   # Check status
   docker-compose logs -f clickup-mcp

3. Health Checks:

   # Check if the service is healthy
   curl http://localhost:3000/health
      
   # View Docker health status
   docker ps

Cloud Deployment

The SSE transport makes the server suitable for cloud deployment platforms:

• Railway: Deploy directly from Git repository
• Heroku: Use the Dockerfile for container deployment
• DigitalOcean App Platform: Configure auto-deployment
• AWS/GCP/Azure: Deploy as container service

Environment Variables for Cloud:

• CLICKUP_API_TOKEN (required)
• PORT (optional, defaults to 3000)

Production Considerations

• Security: Ensure your ClickUp API token is kept secure
• Monitoring: Use the /health endpoint for health checks
• Scaling: The server is stateless and can be horizontally scaled
• SSL/TLS: Use a reverse proxy (nginx/cloudflare) for HTTPS in production

Troubleshooting

Common Issues

"CLICKUP_API_TOKEN environment variable is required"

• Make sure you've set the CLICKUP_API_TOKEN environment variable
• Verify your token is valid by testing it with ClickUp's API directly

"Failed to retrieve teams from ClickUp API"

• Check your API token has the correct permissions
• Verify your internet connection
• Ensure you're not hitting rate limits

"Claude Desktop not showing ClickUp tools"

• Verify the path in claude_desktop_config.json is absolute
• Make sure the server builds without errors: npm run build
• Restart Claude Desktop completely
• Check Claude Desktop logs for errors

TypeScript compilation errors

• Make sure you're using Node.js 16 or higher
• Try cleaning and rebuilding: npm run clean && npm run build
• Check for any missing dependencies: npm install

SSE Transport Issues

• Ensure the port is not already in use: lsof -i :3000
• Check firewall settings if accessing remotely
• Verify the server is accessible: curl http://localhost:3000/health
• For remote access, ensure the host is set correctly: --host 0.0.0.0
• Check CORS settings if connecting from a web client

Remote Connection Issues

• Verify the server is running: check the health endpoint
• Ensure network connectivity between client and server
• Check for proxy or firewall blocking connections
• Verify the correct SSE endpoint URL is being used

Debug Mode

For verbose logging, you can modify the server code to add more console.error statements (they won't interfere with the MCP protocol since they go to stderr).

Contributing

1. Make sure your changes build without errors: npm run build
2. Test your changes with a real ClickUp workspace
3. Test both stdio and SSE transport modes
4. Update documentation as needed
5. Follow TypeScript best practices

Documentation

• README.md: Complete setup and usage guide
• API.md: HTTP endpoint documentation for SSE mode
• config.env.example: Environment configuration template

License

ISC License