sambrody62/clickupmcpserver

ClickUp MCP Server

A Model Context Protocol (MCP) server that provides AI assistants with access to ClickUp's project management capabilities. Deploy on Google Cloud Run for a scalable, serverless solution.

Features

Available Tools

Workspace Management

• clickup_list_workspaces - List all workspaces/teams
• clickup_list_spaces - List spaces in a workspace
• clickup_list_folders - List folders in a space
• clickup_list_lists - List all lists

Task Operations

• clickup_create_task - Create new tasks
• clickup_get_task - Get task details
• clickup_update_task - Update existing tasks
• clickup_delete_task - Delete tasks
• clickup_list_tasks - List and filter tasks

Collaboration

• clickup_add_comment - Add comments to tasks
• clickup_get_comments - Get task comments
• clickup_get_members - List team members

Project Management

• clickup_create_list - Create new lists
• clickup_add_time_entry - Log time entries
• clickup_get_time_entries - Retrieve time tracking data

Prerequisites

• Node.js 20+
• Google Cloud Account with billing enabled
• ClickUp API key (get from ClickUp settings)
• Docker (for containerization)
• Google Cloud CLI (gcloud)

Local Development

Setup

1. Clone the repository and install dependencies:

npm install

2. Create a .env file:

cp .env.example .env
# Edit .env and add your CLICKUP_API_KEY

3. Run in development mode:

npm run dev

4. Test the health endpoint:

curl http://localhost:8080/health

Building

npm run build

Google Cloud Deployment

Quick Deploy

1. Set environment variables:

export GCP_PROJECT_ID="your-project-id"
export CLICKUP_API_KEY="your-clickup-api-key"
export MCP_API_KEY="optional-mcp-api-key"  # For securing the MCP endpoint

2. Run the deployment script:

./deploy.sh

The script will:

• Enable required Google Cloud APIs
• Store API keys in Secret Manager
• Build and push Docker image to Container Registry
• Deploy to Cloud Run
• Output the service URL

Manual Deployment

1. Build the Docker image:

docker build -t gcr.io/YOUR_PROJECT_ID/mcp-server-clickup .

2. Push to Container Registry:

gcloud auth configure-docker
docker push gcr.io/YOUR_PROJECT_ID/mcp-server-clickup

3. Create secrets in Secret Manager:

echo -n "your-clickup-api-key" | gcloud secrets create clickup-api-key --data-file=-
echo -n "your-mcp-api-key" | gcloud secrets create mcp-api-key --data-file=-

4. Deploy to Cloud Run:

gcloud run deploy mcp-server-clickup \
  --image gcr.io/YOUR_PROJECT_ID/mcp-server-clickup \
  --region us-central1 \
  --platform managed \
  --allow-unauthenticated \
  --set-secrets=CLICKUP_API_KEY=clickup-api-key:latest,MCP_API_KEY=mcp-api-key:latest

Client Configuration

After deployment, configure your MCP client to connect to the Cloud Run service:

{
  "mcpServers": {
    "clickup": {
      "url": "https://mcp-server-clickup-xxxxx.run.app/mcp/sse",
      "apiKey": "your-mcp-api-key"
    }
  }
}

API Authentication

The server supports two levels of authentication:

1. ClickUp API Key (Required): Authenticates with ClickUp's API
2. MCP API Key (Optional): Secures the MCP endpoint from unauthorized access

If MCP_API_KEY is set, clients must include it in the Authorization header:

Authorization: Bearer your-mcp-api-key

Architecture

• Transport: HTTP with Server-Sent Events (SSE) for Cloud Run compatibility
• Rate Limiting: Built-in rate limiter respects ClickUp's API limits (100 req/min)
• Error Handling: Comprehensive error handling with meaningful error messages
• Security: API keys stored in Google Secret Manager
• Scalability: Auto-scales on Cloud Run based on demand

CI/CD with Cloud Build

The included cloudbuild.yaml enables automatic deployment on git push:

1. Connect your GitHub repository to Cloud Build
2. Set up a trigger for your main branch
3. Commits will automatically build and deploy

Monitoring

View logs and metrics in Google Cloud Console:

• Cloud Run logs: Shows request logs and application output
• Cloud Monitoring: Track performance metrics
• Error Reporting: Aggregate and analyze errors

Cost Optimization

• Cloud Run charges only when handling requests
• Configure max instances to control costs
• Use Cloud Monitoring to track usage
• Consider setting up budget alerts

Troubleshooting

Common Issues

1. Authentication Failed: Verify your ClickUp API key is correct
2. Rate Limit Exceeded: The built-in rate limiter should prevent this
3. Deployment Fails: Check that all required APIs are enabled
4. Connection Timeout: Increase the timeout in Cloud Run configuration

Debug Mode

For local debugging:

NODE_ENV=development npm run dev

Security Best Practices

1. Always use Secret Manager for API keys
2. Enable MCP_API_KEY for production deployments
3. Configure Cloud Armor for DDoS protection (optional)
4. Set up VPC Service Controls for additional security
5. Regularly rotate API keys

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

MIT