clickup-mcp-full

중첩된 하위 작업 트리 전체를 한 번의 호출로 읽을 수 있는 ClickUp MCP 서버입니다.

이 서버는 @twofeetup/clickup-mcp를 포크하지 않고 래핑하므로, 업스트림 수정 사항은 의존성 업데이트만으로 반영됩니다. 해당 서버 위에 get_task_tree를 추가하고, 작은 모델을 확실히 오도하는 도구 설명 하나를 다시 작성하며, 합리적인 기본 도구 세트를 고정합니다.

왜 필요한가

업스트림에서 하위 작업에 접근하는 유일한 경로는 include_subtasks를 사용한 search_tasks인데, 이는 GET /task/{id}?subtasks=true를 호출하여 직계 자식만의 전체 작업 객체를 반환합니다. 여러 단계로 중첩된 하위 작업 50개가 있는 작업에서는 이 방식은 불완전할 뿐만 아니라 에이전트의 컨텍스트 창을 파괴합니다. 노드마다 요청을 하나씩 보내는 대안은 더 나쁩니다.

대신 get_task_tree는 포함된 리스트를 한 번만 순회합니다. ClickUp의 GET /list/{id}/task?subtasks=true는 리스트의 모든 작업을 parent 포인터와 함께 반환하므로, 트리는 로컬에서 재조립됩니다. 깊이나 너비와 관계없이 총 두 번의 요청만 필요하며, 출력은 작업당 한 줄의 간결한 형식입니다.

Task tree for 86capt3b: 23 task(s) including the root.
Statuses: in progress: 3, open: 14, complete: 6
List: Q3 Delivery

86capt3b  [in progress]  Migrate billing service  <ivan>
  86captk1  [complete]  Audit current schema  <olena>
  86captk2  [in progress]  Write migration scripts  <ivan>
    86captm7  [open]  Handle partial refunds
    86captm8  [open]  Backfill historical rows
  86captk3  [open]  Cutover plan

Related MCP server: ClickUp MCP

설치

클론하거나 빌드할 것이 없습니다. 에이전트가 패키지를 가리키면 첫 실행 시 가져옵니다.

Claude Code

claude mcp add clickup_full_local \
  --env CLICKUP_API_KEY=pk_your_token \
  --env CLICKUP_TEAM_ID=9012345678 \
  -- npx -y github:breckenreed/clickup-mcp-full

Claude Desktop, Cursor, Windsurf 또는 mcpServers JSON을 사용하는 모든 클라이언트

{
  "mcpServers": {
    "clickup_full_local": {
      "command": "npx",
      "args": ["-y", "github:breckenreed/clickup-mcp-full"],
      "env": {
        "CLICKUP_API_KEY": "pk_your_token",
        "CLICKUP_TEAM_ID": "9012345678"
      }
    }
  }
}

Hermes (~/.hermes/config.yaml)

mcp_servers:
  clickup_full_local:
    command: npx
    args: ["-y", "github:breckenreed/clickup-mcp-full"]
    env:
      CLICKUP_API_KEY: "${CLICKUP_API_KEY}"
      CLICKUP_TEAM_ID: "${CLICKUP_TEAM_ID}"
    connect_timeout: 60
    keepalive_interval: 60
    idle_timeout_seconds: 1800

전역 설치 — 매 실행마다 GitHub에서 해석하지 않으려면:

npm install -g github:breckenreed/clickup-mcp-full

그런 다음 인수 없이 clickup-mcp-full을 명령으로 사용합니다.

자격 증명

ClickUp 개인 토큰은 자체적인 범위(scope)가 없습니다. 토큰은 이를 생성한 사용자로 작동하며 해당 사용자의 권한을 상속합니다. 따라서 쓰기 권한이 없는 에이전트가 필요하다면 도구 선택에 의존하지 말고 보기 전용 ClickUp 계정으로 토큰을 생성하세요.

도구

업스트림에는 로컬 파일을 ClickUp에 업로드하는 attach_file_to_task도 포함되어 있습니다. 이 도구는 여기서 기본적으로 비활성화되어 있습니다. 작업별 확인 없이 실행되는 에이전트의 경우, 에이전트가 읽는 모든 프롬프트 인젝션을 데이터 유출 경로로 바꿔버리기 때문입니다. 필요하다면 의도적으로 활성화하세요:

ENABLED_TOOLS=get_workspace_hierarchy,search_tasks,manage_task,task_comments,get_container,manage_container,find_members,operate_tags,task_time_tracking,attach_file_to_task

옵션

공유 워크스페이스에서는 REQUEST_SPACING을 높이세요. 기본값은 초당 약 10회 요청을 허용하지만, ClickUp의 토큰당 한도는 대부분의 요금제에서 분당 약 100회입니다. 한도는 도구가 아닌 토큰에 적용되므로, 에이전트가 한도를 소진하면 같은 토큰으로 실행되는 다른 모든 통합도 중단됩니다. 700으로 설정하면 분당 100회 상한 아래로 유지됩니다.

동작 참고 사항

다른 리스트의 하위 작업. 트리는 루트 작업이 포함된 리스트를 순회하여 구성됩니다. 워크스페이스에서 하위 작업을 상위 작업과 다른 리스트에 배치하는 경우 해당 하위 작업은 나타나지 않으며, 서버는 작업 엔드포인트가 보고하는 직계 자식으로 대체합니다. 이 문제가 발생하고 중요하다면 이슈를 열어주세요.

search_tasks 설명. 업스트림 설명("Works 3 ways")은 작은 모델이 86capt3b 같은 일반 ID를 customTaskId에 넣도록 유도하는데, 이 필드는 DEV-123 같은 접두사 ID 전용입니다. 이러한 호출은 워크스페이스 검색 분기로 넘어가 "At least one filter parameter is required" 오류로 실패하는데, 이는 잘못된 문제를 지적하는 오류입니다. 이후 모델은 필드를 수정하는 대신 필터를 임의로 만들기 쉽습니다. 이 서버는 해당 설명을 모델이 실제로 필요한 단일 규칙으로 대체합니다.

바인드 마운트된 홈 디렉터리로 Docker에서 실행. 에이전트가 HOME을 바인드 마운트로 지정하여 MCP 서버를 실행하는 경우, npx는 연결할 때마다 해당 마운트를 통해 패키지 캐시를 재구축하므로 몇 분이 걸리고 시간 초과가 발생할 수 있습니다. 대신 이미지 내부에 전역으로 설치하고 command:가 바이너리를 가리키게 하세요.

문제 해결

서버가 시작되고 도구를 나열하는지 확인합니다:

CLICKUP_API_KEY=pk_... CLICKUP_TEAM_ID=... npx -y github:breckenreed/clickup-mcp-full --help

Missing required environment는 변수가 프로세스에 도달하지 못했음을 의미합니다. 대부분의 클라이언트는 셸이 아닌 서버 자체의 env 블록에 변수를 요구합니다.

모든 도구에서 401이 발생하면 토큰이 잘못되었거나 취소된 것입니다. 429는 속도 제한에 도달했음을 의미하므로 REQUEST_SPACING을 높이세요.

라이선스

래핑하는 업스트림 서버와 동일하게 MIT입니다. @twofeetup/clickup-mcp는 @taazkareem/clickup-mcp-server의 유료화 이전 트리를 이어받은 MIT 라이선스 커뮤니티 후속 프로젝트입니다.