clickup-mcp

Claude용 ClickUp MCP 서버 — ClickUp 작업, 스페이스, 폴더, 목록, 댓글을 MCP 도구로 노출합니다.

기술 스택: Python 3.12 + uv + FastMCP (Starlette/FastAPI)

빠른 시작

# Install dependencies
cd D:\leo\mcp-server\clickup-mcp
uv sync

# Run in stdio mode (for Claude Desktop)
$env:CLICKUP_API_TOKEN="pk_xxxxx"
uv run clickup-mcp

Related MCP server: Clickup Universal MCP Server

구성

.env.example을 .env로 복사하고 값을 입력하세요:

API 토큰 받기: ClickUp → Settings → Apps → API Token

Claude Desktop 설정

claude_desktop_config.json에 추가하세요:

{
  "mcpServers": {
    "clickup": {
      "command": "uv",
      "args": ["run", "--directory", "D:/leo/mcp-server/clickup-mcp", "clickup-mcp"],
      "env": {
        "CLICKUP_API_TOKEN": "pk_xxxxx"
      }
    }
  }
}

전송 모드

stdio (Claude Desktop / CLI)

$env:CLICKUP_API_TOKEN="pk_xxxxx"
uv run clickup-mcp

HTTP — 단일 테넌트

$env:CLICKUP_API_TOKEN="pk_xxxxx"
$env:MCP_TRANSPORT="http"
$env:MCP_HTTP_PORT="8080"
uv run clickup-mcp

HTTP — gateway / 멀티 테넌트

$env:MCP_TRANSPORT="http"
$env:AUTH_MODE="gateway"
uv run clickup-mcp
# Each request must include: X-Clickup-Token: pk_xxxxx

사용 가능한 도구 (28)

개인의 ClickUp 사용자 ID 찾기

clickup_list_members를 사용하세요. ClickUp의 네이티브 GET /team 응답에는 팀별 전체 멤버 목록(teams[].members[].user.{id,username,email})이 포함되어 있지만, clickup_get_workspaces는 응답을 작게 유지하기 위해 이를 제거하므로 사람을 찾는 용도로는 적합하지 않습니다. clickup_list_members는 동일한 기본 엔드포인트를 읽고 멤버 목록을 평평한 전용 형태(id/username/email/team_id/role)로 투영하여 호출자가 전체 워크스페이스/팀 객체에서 직접 꺼내지 않아도 됩니다. clickup_list_tasks_for_person은 내부적으로 동일한 기본 조회를 사용하여 email -> user_id를 해석합니다.

알려진 한계: ClickUp의 팀 멤버 객체에는 "이 멤버가 비활성화되었는지"를 나타내는 신뢰할 수 있는 필드가 없습니다. 실제로 이를 뒷받침할 데이터가 없으므로 clickup_list_members는 active 필드를 반환하지 않습니다 (원시 객체에 존재하는 유일한 status 필드인 invited_by.status는 멤버가 아닌 초대자를 설명합니다).

clickup_search_tasks는 이미 status.type을 반환합니다

여기의 다른 모든 읽기 도구와 마찬가지로, clickup_search_tasks와 clickup_get_task는 ClickUp의 원시 작업 객체를 수정하지 않고 그대로 전달합니다 — status 객체의 type 필드(open / custom / closed / done)를 포함하며, 이는 사용자 정의 이름의 상태가 완료로 간주되는지 판단할 수 있는 유일한 신뢰할 수 있는 방법입니다. 이를 위한 코드 변경은 필요하지 않았습니다; 이미 그렇게 되어 있었습니다. clickup_list_tasks_for_person은 편의를 위해 각 반환 작업에 이를 status_type으로 명시적으로 표시합니다.

이 ClickUp 워크스페이스에서 EOS Rocks가 표현되는 방식

실제 rock 작업의 필드를 직접 검사하여 2026-08-18에 확인되었습니다(추측 아님): Rocks는 문자 그대로 "Rocks"라는 이름의 목록에 들어 있는 일반 ClickUp 작업입니다 (Space "Company" > Folder "EOS Traction" 아래에 있음). 각 작업은 전용 사용자 정의 필드를 가집니다: Quarter (드롭다운, "Q1 2024".."Q4 2026"), Rocks Status (On Hold / Off Track / On Track / Completed / Blocked / At Risk), Rock Type (Company / Individual / Departmental / Team Rock), Department, 그리고 진행률은 Progress(수동) 또는 Progress %(자동, 체크리스트 롤업)로 표시됩니다. 이것은 ClickUp Goals API도 아니고 메타데이터가 없는 단순 작업 목록도 아닙니다 — 작업과 사용자 정의 필드의 조합입니다.

clickup_list_rocks_for_org는 토큰에 표시되는 모든 워크스페이스에서 "Rocks"라는 이름의 모든 목록을 (하드코딩된 ID가 아닌 이름으로, 스페이스/폴더가 재구성되는 경우를 대비해) 검색하여 이 필드들을 읽고 정규화합니다:

• quarter: ClickUp의 "Q3 2026" 라벨은 2026-Q3으로 변환됩니다 (그리고 quarter 입력 필터를 위해 다시 역변환됩니다).

• status: ClickUp의 6가지 원시 옵션은 5값 규약(on_track/off_track/done/missed/open)으로 매핑됩니다 — 정확한 매핑과 missed가 절대 생성되지 않는 이유는 rocks.py의 _STATUS_MAP 주석을 참고하세요 (ClickUp 데이터에는 "시간이 부족함"과 일반적인 "off track"을 구분하는 항목이 없습니다; 기한이 지난 due_date에서 이를 도출하는 것은 확인되지 않은 비즈니스 로직 가정이므로 여기서는 수행하지 않습니다).

• measurable: 이 목록에는 전용 필드가 없습니다. 작업 설명으로 폴백합니다; 그것도 비어 있으면 null입니다 (절대 임의로 만들지 않음).

• weekly_status: 구조화된 소스가 어디에서도 발견되지 않았습니다 (사용자 정의 필드도, 댓글에서 파생된 것도 없음) — 항상 []로 반환됩니다. 조직이 ClickUp에서 다른 방식으로 이를 추적하기 시작하면 다시 검토하세요.

첨부 파일 및 이미지

ClickUp REST API에는 파일을 댓글에 직접 첨부하는 방법이 없습니다 — 작업에만 첨부할 수 있습니다 (POST /task/{task_id}/attachment, clickup_attach_task_file이 래핑하는 엔드포인트). 첨부 파일 삭제/업데이트 엔드포인트도 없습니다; 다시 업로드하면 기존 첨부 파일을 교체하는 대신 새 첨부 파일이 추가되며, 삭제하려면 ClickUp 웹/데스크톱 앱이 필요합니다. ClickUp 자체 공식 MCP 서버의 도구 설명을 확인해서도 확인되었습니다 — 동일하게 분리되어 있습니다 (첨부 파일을 지원하지 않는 Create Task Comment 도구와 별도의 Attach File to Task 도구).

댓글 안에 이미지를 인라인으로 표시하려면, 기본 원리는 다음과 같습니다: 먼저 파일을 작업에 업로드한 다음, 파일 응답에서 반환된 URL을 댓글 텍스트에서 Markdown 이미지 구문으로 참조하는 것입니다 — ClickUp의 댓글 렌더러는 이를 단순한 링크가 아닌 실제 이미지로 인라인 처리합니다. clickup_create_comment_with_image는 두 단계를 한 번의 호출로 수행합니다:

clickup_create_comment_with_image(task_id, file_content_base64, filename)
# internally:
#   1. POST /task/{task_id}/attachment  -> {"url": "...", ...}
#   2. POST /task/{task_id}/comment     comment_text = "![filename](url)"

대신 수동으로 수행하려면(예: 이미지 주변에 다른 텍스트를 추가하려면) 두 도구를 직접 호출하세요:

1. result = clickup_attach_task_file(task_id, file_content_base64, filename)
   -> result["url"] is the uploaded file's URL

2. clickup_create_task_comment(
     task_id,
     comment_text=f"![{filename}]({result['url']})"
   )

API 참조

• ClickUp API v2 Docs

• Create Task Attachment