# 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:
```bash
npm install
```

2. Create a `.env` file:
```bash
cp .env.example .env
# Edit .env and add your CLICKUP_API_KEY
```

3. Run in development mode:
```bash
npm run dev
```

4. Test the health endpoint:
```bash
curl http://localhost:8080/health
```

### Building

```bash
npm run build
```

## Google Cloud Deployment

### Quick Deploy

1. Set environment variables:
```bash
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:
```bash
./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:
```bash
docker build -t gcr.io/YOUR_PROJECT_ID/mcp-server-clickup .
```

2. Push to Container Registry:
```bash
gcloud auth configure-docker
docker push gcr.io/YOUR_PROJECT_ID/mcp-server-clickup
```

3. Create secrets in Secret Manager:
```bash
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:
```bash
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:

```json
{
  "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:
```bash
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