Clickup Integration

ClickUp Integration Skill

Integration patterns for syncing development sessions with ClickUp tasks.

Architecture Overview

┌─────────────────────────────────────────────────────────────────┐
│                     CLICKUP INTEGRATION                          │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ┌─────────────┐     ┌──────────────┐     ┌──────────────┐     │
│  │   Claude    │────►│  MCP Server  │────►│   ClickUp    │     │
│  │   Session   │◄────│  (clickup)   │◄────│     API      │     │
│  └─────────────┘     └──────────────┘     └──────────────┘     │
│         │                                        │              │
│         ▼                                        ▼              │
│  ┌─────────────┐                         ┌──────────────┐      │
│  │  Session    │                         │   Webhooks   │      │
│  │  Files      │                         │  (optional)  │      │
│  └─────────────┘                         └──────────────┘      │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

When to Use This Skill

• Setting up ClickUp integration for the first time
• Syncing development sessions with ClickUp tasks
• Creating tasks from Claude sessions
• Updating task status automatically
• Reading task details and comments

Configuration

.claude/config/workspace.json

{
  "taskManager": {
    "enabled": true,
    "provider": "clickup",
    "syncWithSession": true,
    "autoUpdateStatus": true,
    "config": {
      "apiKey": "${CLICKUP_API_KEY}",
      "workspaceId": "your-workspace-id",
      "defaultSpace": "your-default-space-id",
      "useMcp": true,
      "mcpFallback": true
    }
  }
}

Environment Variables

# .env.local
CLICKUP_API_KEY=pk_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

MCP Server Integration

ClickUp provides an MCP server for Claude Code integration.

Setup

# Add MCP server to Claude Code
claude mcp add clickup

Available MCP Tools

Example Usage

// Get task details via MCP
const task = await mcp.clickup.get_task({ task_id: "abc123" });

// Create task via MCP
const newTask = await mcp.clickup.create_task({
  list_id: "12345678",
  name: "Implement user authentication",
  description: "Add OAuth2 support",
  priority: 2,
  tags: ["feature", "auth"]
});

API Patterns

Authentication

// API Key authentication
const headers = {
  'Authorization': process.env.CLICKUP_API_KEY,
  'Content-Type': 'application/json'
};

// Base URL
const BASE_URL = 'https://api.clickup.com/api/v2';

Common Endpoints

Task Structure

interface ClickUpTask {
  id: string;
  custom_id: string | null;
  name: string;
  description: string;
  status: {
    status: string;
    color: string;
    type: string;
  };
  priority: {
    id: string;
    priority: string;
    color: string;
  };
  assignees: Array<{
    id: number;
    username: string;
    email: string;
  }>;
  tags: Array<{
    name: string;
    tag_fg: string;
    tag_bg: string;
  }>;
  due_date: string | null;
  start_date: string | null;
  time_estimate: number | null;
  custom_fields: Array<{
    id: string;
    name: string;
    value: any;
  }>;
  url: string;
}

Session Sync Patterns

Linking Session to Task

# In requirements.md

## ClickUp Task
- **Task ID:** abc123
- **URL:** https://app.clickup.com/t/abc123
- **Status:** In Progress

Auto-Update Status

When autoUpdateStatus: true, Claude updates task status:

Comment Sync

// Post session progress as comment
await mcp.clickup.create_task_comment({
  task_id: "abc123",
  comment_text: `
## Session Progress Update

**Phase:** Backend Development
**Progress:** 60%

### Completed
- API endpoints created
- Tests written

### In Progress
- Frontend components

### Blocked
- None
  `.trim()
});

Webhook Configuration

Setting Up Webhooks

// Create webhook for task updates
POST /team/{team_id}/webhook
{
  "endpoint": "https://your-app.com/api/webhooks/clickup",
  "events": [
    "taskCreated",
    "taskUpdated",
    "taskDeleted",
    "taskStatusUpdated",
    "taskCommentPosted"
  ]
}

Webhook Events

Handling Webhooks

// app/api/webhooks/clickup/route.ts
export async function POST(request: Request) {
  const payload = await request.json();

  switch (payload.event) {
    case 'taskStatusUpdated':
      // Handle status change
      break;
    case 'taskCommentPosted':
      // Handle new comment
      break;
  }

  return Response.json({ received: true });
}

Rate Limiting

Limits

Handling Rate Limits

// Check rate limit headers
const remaining = response.headers.get('X-RateLimit-Remaining');
const reset = response.headers.get('X-RateLimit-Reset');

if (remaining === '0') {
  const waitTime = parseInt(reset) - Date.now();
  await sleep(waitTime);
}

Error Handling

Common Error Codes

Error Response Format

{
  "err": "Task not found",
  "ECODE": "TASK_024"
}

Testing Patterns

Mock API Responses

// __mocks__/clickup.ts
export const mockTask = {
  id: "abc123",
  name: "Test Task",
  status: { status: "Open", color: "#d3d3d3" },
  priority: { priority: "normal" }
};

export const mockGetTask = jest.fn().mockResolvedValue(mockTask);

Integration Tests

describe('ClickUp Integration', () => {
  it('should fetch task details', async () => {
    const task = await clickup.getTask('abc123');
    expect(task.name).toBeDefined();
  });

  it('should create task', async () => {
    const task = await clickup.createTask({
      listId: '12345',
      name: 'New Task'
    });
    expect(task.id).toBeDefined();
  });
});

Anti-Patterns

DON'T: Hardcode API Keys

// BAD
const apiKey = 'pk_12345_abcdef';

// GOOD
const apiKey = process.env.CLICKUP_API_KEY;

DON'T: Ignore Rate Limits

// BAD
for (const task of tasks) {
  await updateTask(task);
}

// GOOD
for (const task of tasks) {
  await updateTask(task);
  await sleep(100); // Respect rate limits
}

DON'T: Store Sensitive Data in Tasks

// BAD - Don't put secrets in task descriptions
description: `API Key: ${apiKey}`

// GOOD - Reference environment variables
description: `Uses API key from CLICKUP_API_KEY env var`

Checklist

Before using ClickUp integration:

• API key configured in environment
• Workspace ID set in .claude/config/workspace.json
• Default space configured
• MCP server added (if using MCP)
• Webhook endpoint set up (if using webhooks)
• Error handling implemented
• Rate limiting considered

Related Skills

• session-management - Session lifecycle
• scheduled-actions - Background task processing
• service-layer - API implementation patterns