ClickUp MCP Server

ClickUp용 Model Context Protocol 서버로, 두 가지 아이디어를 기반으로 합니다:

모든 것은 사람이 읽을 수 있는 이름을 사용합니다. find(scope: "Cavalry/Findings", assignee: "me", due: "overdue") — ID가 필요 없고, 트리를 탐색해 찾을 필요도 없습니다. 이름이 해석되지 않으면 유효한 옵션을 나열하는 오류를 발생시킵니다. 자신 있게 빈 결과를 반환하는 것은 실패보다 나쁘기 때문입니다.

할 수 있는 일을 직접 선택합니다. 네 가지 기능 프로필이 모든 나가는 요청에 적용됩니다. 무인 에이전트에 agent 프로필을 주면 작업과 댓글을 만들 수 있지만 기존 항목을 수정하거나 삭제할 수는 없습니다.

도구 18개, 테스트 354개. 버전 4.3.0 — CHANGELOG.md를 참조하세요. nsxdavid/clickup-mcp-server의 대대적으로 개조된 포크입니다.

상태: 4.x는 새 버전입니다. 다섯 차례의 적대적 레드팀 테스트를 거쳤지만 아직 프로덕션에서 실행되지는 않았습니다. 이전 3.x 라인은 여전히 이 저장소에 포함되어 있으며 참조 배포가 실행하는 버전이기도 합니다 — 3.x 실행을 참조하세요.

빠른 시작

ClickUp → Settings → Apps → API Token에서 토큰을 받으세요(pk_로 시작합니다). 작업공간은 자동으로 발견됩니다 — 구성할 다른 것은 없습니다.

설치 없이:

{
  "mcpServers": {
    "clickup": {
      "command": "npx",
      "args": ["-y", "github:benthesoundguy/clickup-mcp-server"],
      "env": { "CLICKUP_API_TOKEN": "pk_your_token_here" }
    }
  }
}

또는 클론으로부터, 무엇이든 변경할 계획이라면 이 방법을 원할 것입니다:

git clone https://github.com/benthesoundguy/clickup-mcp-server
cd clickup-mcp-server
npm install          # builds automatically
npm run check        # verifies the token and connects — do this before wiring up a client

{
  "mcpServers": {
    "clickup": {
      "command": "node",
      "args": ["/absolute/path/to/clickup-mcp-server/build/v4/index.js"],
      "env": { "CLICKUP_API_TOKEN": "pk_your_token_here" }
    }
  }
}

해당 블록이 들어가는 위치

위 형태는 Claude Desktop, Claude Code, Cursor, Cline, Windsurf에서 그대로 작동합니다 — 모두 mcpServers 키를 사용합니다. 두 클라이언트는 다릅니다:

• VS Code (.vscode/mcp.json)는 mcpServers 대신 servers를 사용합니다. 내부 형태는 동일합니다. Cursor 구성을 그대로 복사하는 것이 가장 흔한 설정 실수입니다.

• Zed (settings.json)는 context_servers를 사용하며, 명령을 중첩합니다:

  { "context_servers": { "clickup": { "command": { "path": "node", "args": ["/path/to/build/v4/index.js"] } } } }

Claude Code는 파일을 완전히 건너뛸 수 있습니다:

claude mcp add clickup --env CLICKUP_API_TOKEN=pk_... -- npx -y github:benthesoundguy/clickup-mcp-server

대신 파일에 토큰 넣기

클라이언트 구성에 토큰을 붙여 넣고 싶지 않다면 — 데스크톱 앱이 해당 파일을 다시 작성하고 오래된 사본을 유지할 수 있습니다 — 설치 위치 옆의 .env 파일에 넣고 env 블록을 완전히 생략하세요:

echo 'CLICKUP_API_TOKEN=pk_your_token_here' > .env

서버는 <cwd>/.env, <install>/.env, <install>/../.env 순서로 찾아보고 시작 시 어떤 파일을 사용했는지 알려줍니다. 파일의 토큰이 환경 변수보다 우선하므로 한 곳에서 토큰을 교체하면 실제로 적용됩니다. 다른 모든 설정은 반대로 작동합니다 — 클라이언트 구성의 명시적 값이 항상 우선하므로, 방치된 .env가 MCP_PROFILE을 넓힐 수 없습니다. 서버에서 MCP_STRICT_ENV=1을 설정하면 전체 조회를 끌 수 있습니다.

작동하지 않을 때

npm run check          # from a clone
node build/v4/index.js --check

이 명령은 서버가 해석한 모든 입력을 출력합니다 — 찾은 .env와 적용된 내용, 토큰이 존재하고 올바른 형태인지 여부, 활성 프로필과 도구 수, Node 버전과 빌드 스탬프 — 그런 다음 실제로 ClickUp에 연결하여 사용자가 누구인지와 요율 한도를 보고합니다. 토큰은 절대 출력하지 않으므로 이슈에 붙여 넣어도 안전합니다.

토큰이 없으면 서버는 stdio 모드에서 조용히 죽지 않습니다. 서버는 시작하고 도구를 등록하며, 모든 호출에 무엇이 잘못되었고 어떻게 고치는지 답하므로 문제는 찾아다녀야 하는 로그 파일이 아니라 대화에 나타납니다. (HTTP 모드에서는 여전히 1로 종료됩니다 — 무인 배포는 크게 실패해야 합니다.)

Related MCP server: ClickUp MCP Server

기능 프로필

하나의 바이너리, 네 가지 프로필, MCP_PROFILE로 선택합니다. 한 번 설치하고 프로필별로 클라이언트 항목을 추가하여 각 에이전트가 가져야 할 프로필을 활성화하세요.

스키마 비용은 도구 정의가 모든 요청에서 작업이 발생하기 전에 모델 컨텍스트에서 소비하는 양입니다. 비교를 위해, 3.x는 88개 도구에 대해 ~18,600토큰을 소비합니다.

agent가 흥미로운 프로필입니다. 추가는 할 수 있지만 수정이나 삭제는 절대 할 수 없으므로, 무인 에이전트가 할 수 있는 최악의 일은 삭제할 수 있는 어수선함을 만드는 것입니다. 이 보장은 세 계층으로 적용되며, 오직 세 번째만 보안 경계입니다:

1. 도구 필터링 — 어떤 도구가 전혀 나타나는지 (컨텍스트 비용 + 도구 선택)

2. 작업 필터링 — 도구가 광고하는 작업 (컨텍스트 비용 + 정직성)

3. 쓰기 정책 — 업로드를 포함한 모든 나가는 요청에서 검사되는 허용 목록 ← 그 보장

계층 1과 2는 모든 향후 기여자가 모든 도구를 올바르게 태그하는 데 의존합니다. 계층 3은 그렇지 않습니다. 실제 요청이 나가는 길에 검사하므로, 잘못 태그된 도구, 리팩터링, 내년에 추가될 엔드포인트가 프로필을 넓힐 수 없습니다. 테스트 스위트는 agent 컨텍스트로 core 전용 핸들러를 직접 호출하여 계층 1과 2를 완전히 우회하고, 아무것도 네트워크에 도달하지 않음을 단언함으로써 이를 증명합니다.

추가적으로 보이지만 의도적으로 agent에서 제외된 것들: 태그 첨부, 사용자 정의 필드 설정, 종속성 추가는 모두 기존 작업을 변경합니다. 웹훅 생성은 데이터를 외부 엔드포인트로 스트리밍하기 시작합니다. 추가 전용과 안전은 같은 속성이 아닙니다.

기본값이 full이 아니라 core인 이유

full은 멤버십 관리를 부여합니다 — 사용자 초대는 청구 가능한 좌석을 소비하고, 제거는 실제 사람의 접근 권한을 변경합니다 — 여기에 작업공간 데이터를 외부로 보내는 웹훅도 포함됩니다. 그 어느 것도 첫 연결의 목적이 아니며, 아무도 변경하지 않는 기본값은 안전한 것이어야 합니다. 관리 권한이 필요할 때는 이름을 명시하여 요청하세요. 요청하지 않는 한, 거부 메시지가 정확히 그 방법을 알려줍니다.

첨부 파일과 파일 시스템

attach는 서버가 실행되는 머신에서 파일을 읽습니다. 이는 쓰기 정책이 볼 수 없는 리소스입니다 — 정책은 URL을 검사하는데 파일 읽기에는 URL이 없습니다 — 따라서 CLICKUP_ATTACH_ROOT로 별도로 관리됩니다:

• 설정됨 → 읽기는 해당 디렉터리로 제한됩니다. 제한은 ..과 모든 심볼릭 링크를 해석한 후 파일의 실제 경로를 기준으로 검사됩니다.

• 설정 안 됨 → core와 full은 프로세스가 읽을 수 있는 모든 파일을 읽을 수 있습니다. agent에서는 attach가 전혀 제공되지 않습니다 (13개 대신 12개 도구), 안전한 기본 루트가 없기 때문입니다. 작업 디렉터리는 일반적으로 프로젝트 디렉터리이고, 그곳에 .env가 있습니다.

잘못 구성된 루트는 무시되지 않고 시작 시 치명적입니다 — 조용히 존재하지 않는 경계는 없는 것보다 나쁩니다.

도구

도구는 적절한 곳에서 사라지기보다 축소됩니다. read에서 comment는 읽기 인자만 표시하고 checklist는 list만 광고하므로, 스키마는 거부될 작업을 광고하는 대신 이 연결이 할 수 있는 일에 대해 진실을 말합니다.

모든 것이 따르는 규칙

자신 있게 틀린 답을 반환하지 마십시오. ClickUp은 잘못된 입력에 명랑한 넌센스로 응답하기 때문에 틀리기 쉽습니다:

그래서 이 서버는 이름을 해석하고 모호할 때 오류를 발생시킵니다 ("Findings"가 네 개의 목록과 일치하면 어느 하나를 임의로 고르는 대신 네 개를 모두 명명하는 오류입니다); 필터 값이 해석되지 않으면 빈 결과 대신 오류를 발생시킵니다; 목록이 실제로 받아들이는 값에 대해 클라이언트 측에서 열거형을 검증합니다; 신뢰할 수 없는 쓰기를 객체를 다시 읽어 확인합니다; 그리고 수를 절대 과장하지 않습니다 — 페이지네이션이 중단된 쿼리는 100+ matches를 보고하고, 클라이언트 측 필터는 실제로 스캔한 양을 보고합니다.

오류는 무엇이 실패했는지, 왜 실패했는지, 다음에 무엇을 해야 하는지를 말하며 유효한 옵션을 나열합니다.

환경 변수

원격 모드(Claude 웹 + 모바일 및 모든 HTTP 클라이언트)

서버는 streamable HTTP를 사용하며 세 가지 독립적인 자격 증명을 허용합니다. 그중 하나라도 요청을 인증합니다. 서로 다른 클라이언트가 서로 다른 것을 제시할 수 있으므로 함께 공존하도록 설계되었습니다.

MCP_TRANSPORT=http MCP_AUTH_TOKEN=$(openssl rand -hex 24) \
MCP_PROFILE=core CLICKUP_API_TOKEN=... node build/v4/index.js

GET /health는 버전, 활성 프로필, 도구 수 및 첨부 루트를 보고하는 인증되지 않은 프로브입니다.

OAuth(호스팅 클라이언트가 원하는 것)

이 서버는 OAuth 제공자가 될 필요가 없으며, 실제로도 그렇지 않습니다. 2025-06-18 MCP 사양 이후로 MCP 서버는 리소스 서버입니다. 즉, 신뢰하는 인증 서버를 지정하고 해당 서버가 발급한 토큰을 검증합니다. 로그인, 동의 및 토큰 발급은 IdP — Cloudflare Access, WorkOS, Auth0, Descope, Stytch, Keycloak 등 OIDC discovery를 지원하는 모든 것 — 의 몫입니다.

MCP_TRANSPORT=http \
MCP_PUBLIC_URL=https://mcp.example.com \
MCP_OAUTH_ISSUER=https://your-idp.example.com \
CLICKUP_API_TOKEN=pk_... node build/v4/index.js

이것이 전체 구성입니다. 그러면 서버는 다음을 수행합니다:

• /.well-known/oauth-protected-resource에서 RFC 9728 Protected Resource Metadata를 발급자와 함께 인증 없이 제공합니다;

• 인증되지 않은 요청에 401과 해당 문서를 가리키는 WWW-Authenticate 헤더로 응답합니다. 이것이 클라이언트가 로그인 위치를 발견하는 방법입니다;

• /.well-known/openid-configuration(또는 RFC 8414)을 통해 발급자의 서명 키를 발견하거나, 설정한 경우 MCP_OAUTH_JWKS_URL을 사용합니다;

• 모든 토큰을 검증합니다: RS256 고정, 발급자의 JWKS에 대한 서명, exp, nbf, iss, 그리고 aud — 토큰은 이 서버를 지정해야 합니다.

마지막 검사가 가장 중요합니다. 이 검사가 없으면 IdP가 다른 서비스용으로 발행한 토큰이 여기서 재사용될 수 있습니다. 이것이 MCP_PUBLIC_URL이 추론되는 것이 아니라 필수인 이유입니다: 예상 audience는 요청에서 절대 나와서는 안 되며, Host 헤더는 호출자가 설정하기 때문입니다.

발급자가 구성되면 MCP_AUTH_TOKEN은 선택 사항이 됩니다 — OAuth 전용 배포에는 사용하지도 않을 공유 암호가 필요 없습니다.

Dynamic Client Registration 참고 사항. 2026-07-28 사양은 DCR을 더 이상 사용하지 않고 Client ID Metadata Documents를 채택했습니다. 이 변경은 인증 서버와 클라이언트에 적용됩니다. 리소스 서버는 어느 쪽이든 영향받지 않으므로, 자체 AS를 구축하는 대신 위임해야 하는 좋은 이유입니다.

claude.ai 커넥터 주의 사항

Claude의 사용자 지정 커넥터 UI는 OAuth 필드만 허용합니다 — Authorization URL, Token URL, Client ID, Client Secret. 정적 bearer 토큰이나 사용자 지정 헤더를 위한 필드는 없습니다 (#112, #411). 따라서:

• OAuth가 구성된 경우, 일반 사용자 지정 커넥터로 연결하세요. 이것이 의도된 경로입니다.

• OAuth가 없는 경우, 유일한 방법은 MCP_ALLOW_TOKEN_IN_PATH=1로 활성화되는 URL 내 토큰 형식 /mcp/<token>입니다. 작동은 하지만 자격 증명이 프록시가 기록하는 URL에 들어가며, 이것이 strict 모드가 이를 거부하는 이유입니다. 배포가 아닌 임시 해결책으로 취급하세요.

Cloudflare Access(선택적 세 번째 인증 모드)

CF_ACCESS_TEAM_DOMAIN과 CF_ACCESS_AUD를 설정하면 서버는 Access가 전달하는 모든 요청에 넣는 Cf-Access-Jwt-Assertion 헤더를 검증합니다: 팀 JWKS에 대한 RS256, 그리고 exp, iss, aud. 두 Access 흐름 모두 하나의 경로로 검증됩니다 — 브라우저 로그인은 email을, 서비스 토큰은 common_name을 담습니다.

이것은 심층 방어입니다. Access를 통과하지 않고 오리진에 도달하는 요청 — 터널 구성 오류, 두 번째 인그레스, 호스트 네트워크의 무언가 — 은 Access로 인증된 호출자를 가장할 수 없습니다. 기본적으로 차단하는 방식으로 실패합니다: alg는 RS256으로 고정되고(alg: none 및 HS256 혼동이 거부됨), 도달할 수 없는 JWKS는 우회가 아니라 거부하며, JWKS URL은 토큰이 아닌 구성에서 가져옵니다.

Bearer 인증은 계속 작동합니다. 요청은 유효한 Access JWT 또는 유효한 bearer 토큰으로 인증되므로, 헤더를 지원하는 에이전트는 변경이 필요 없습니다.

오리진은 /.well-known/oauth-*를 제공하지 않습니다 — Managed OAuth가 활성화되면 Access가 인증 서버가 되어 엣지에서 discovery를 제공합니다.

Strict 모드(MCP_STRICT_ENV=1)

무인 배포를 위한 자세입니다. 비밀은 환경에서 와야 하며, 서버는 자격 증명을 만들어내거나 영구 저장하지 않고, 잘못 구성된 채 시작하는 대신 실행 가능한 메시지와 함께 1로 종료됩니다. 또한 프록시 액세스 로그에 자격 증명이 남는 URL 경로 토큰 형식도 거부합니다.

이것이 중요한 이유는 .env 파일 조회가 의도적으로 process.env보다 우선하기 때문입니다 — 데스크톱 호스트는 종료 시 메모리에서 자체 구성 파일을 다시 쓰므로 파일이 거기서 이겨야 합니다. 서버에서는 그 우선순위가 거꾸로입니다: 작업 디렉터리의 우연한 .env 파일이 systemd 유닛을 조용히 압도할 수 있습니다. strict 모드는 이 조회를 끕니다.

전체 레시피는 deploy/DEPLOY.md를 참조하세요: VPS 설정 스크립트, 강화된 systemd 유닛, Cloudflare Tunnel, 그리고 Claude에 연결하기.

3.x에서 업그레이드

도구 이름이 완전히 다릅니다 — 4.x는 이름 변경이 아니라 재작성입니다. 하드코딩된 3.x 도구 이름(저장된 프롬프트, 에이전트 지침, 스크립트)을 보유한 모든 것은 업데이트가 필요합니다.

매핑은 대부분 다대일입니다:

이관되지 않은 항목: project_intelligence(8개의 로컬 분석 보고서) 및 reminders_create. 상태 관리 — 상태 생성, 이름 변경, 재정렬 — 도 존재하지 않습니다. meta는 상태를 읽지만 변경하지는 않습니다. 이러한 기능이 필요하면 3.x를 실행하세요.

3.x 실행

3.x는 여전히 이 저장소에서 빌드되어 배포됩니다:

npm run start:v3       # via the package script
node build/index.js    # the 3.x entry point directly

계속 사용하려면 MCP 클라이언트가 build/v4/index.js 대신 build/index.js를 가리키게 하세요.

deploy/의 참조 systemd 유닛은 의도적으로 여전히 3.x에 고정되어 있습니다. 실행 중인 서비스가 패키지 기본값이 그 아래에서 변경되었다고 해서 주요 버전을 바꾸면 안 되기 때문입니다. ExecStart가 build/v4/index.js를 가리키도록 하고 MCP_PROFILE을 명시적으로 설정하여 마이그레이션하세요.

알려진 ClickUp API 제한 사항

여기서는 버그가 아닙니다 — API에 실제로 이러한 기능이 없으며, 이 서버는 이를 속여서 해결하는 대신 제한 사항을 보고합니다.

• 작업은 목록 간에 이동할 수 없습니다. POST /list/{dest}/task/{id}는 "Tasks in Multiple Lists" ClickApp 없이는 200 {}을 반환하고 아무것도 하지 않습니다. list_id를 사용한 PUT은 조용히 무시되고, /move는 404를 반환합니다. update의 이동 경로는 작업을 다시 읽어와서 이동이 발생하지 않았음을 보고하는 대신 큰 소리로 실패합니다.

• 첨부 파일에는 목록 엔드포인트가 없습니다. — task는 작업 객체에서 첨부 파일을 읽어옵니다. 업로드는 multipart 전용이며 25MB로 제한됩니다.

• 문서(Docs) 는 이름을 바꾸거나 삭제할 수 없으며, 페이지도 삭제할 수 없습니다.

• 사용자 정의 필드 정의 는 나열하고 생성할 수 있지만, 편집하거나 삭제할 수는 없습니다.

• 날짜 사용자 정의 필드는 Unix 밀리초를 요구합니다. 해당 필드에 YYYY-MM-DD 형식은 ClickUp에서 거부됩니다. 작업의 due_date/start_date는 두 형식을 모두 허용하며 여기서 변환됩니다.

• 상태 및 태그 이름은 소문자로 저장됩니다. 여기서는 전체적으로 대소문자를 구분하지 않고 매칭합니다.

• 목록은 스페이스의 상태를 지속적으로 재정의하므로, "유효한 상태가 무엇인지"는 목록별 질문입니다. meta가 목록별로 답변합니다.

• ClickUp은 잘못된 열거형에 HTTP 500으로 응답하므로, 열거형은 전송 전에 클라이언트 측에서 검증됩니다.

• 속도 제한은 대략 토큰당 분당 100회 요청이며, 이를 사용하는 모든 항목이 공유합니다. whoami는 실시간 예산을 보고하며, 서버는 x-ratelimit-* 헤더에 맞춰 자체적으로 속도를 조절합니다.

웹훅 수신기(선택 사항)

외부 인프라 없이 ClickUp 웹훅 이벤트를 처리합니다:

WEBHOOK_PORT=3001 WEBHOOK_SECRET=your_secret node build/webhook-receiver/index.js

• 원시 요청 본문에 대한 HMAC-SHA256 검증; 시크릿이 구성된 경우 서명되지 않은 요청은 거부됩니다

• 구조화된 이벤트 파싱 — 유형, 객체, 작업, 변경 사항, 사용자, 타임스탬프

• 콜백 URL로의 선택적 전달(WEBHOOK_FORWARD_URL)

• 순수 Node.js http, 추가 의존성 없음

개발

npm install
npm run build
npm test          # 354 tests, mocked HTTP — no token needed
npm run smoke     # live CRUD walk (needs CLICKUP_API_TOKEN; creates and
                  # deletes its own sandbox in your workspace)

4.x에 대한 아키텍처 노트는 src/v4/README.md에 있으며, 설계 근거와 측정 결과는 V4-PLAN.md에 있습니다.

"작동하지 않는" 수정 사항 디버깅

whoami를 호출하세요. 실행 중인 빌드의 버전과 스탬프를 보고합니다. MCP 호스트는 세션 시작 시 자체 서버 프로세스를 생성하고 이를 유지하므로, 재빌드는 이미 실행 중인 세션에 도달하지 않습니다 — 스탬프가 변경 사항보다 이전이라면 호스트 앱을 다시 시작하세요. 이 도구가 존재하기 전에는 이로 인해 여러 차례 유령 버그 보고가 발생했습니다.

라이선스

MIT — LICENSE 참조. David Whatley의 nsxdavid/clickup-mcp-server에서 포크되었습니다.