acuity-mcp

로컬 MCP 서버로, Acuity Scheduling API를 Claude Code 도구로 노출합니다 — 약속 목록 보기/생성/일정 변경/취소, 가용성 확인, 약속 유형, 캘린더 및 클라이언트 목록 보기 등을 Claude 세션에서 직접 수행할 수 있습니다. 여러 Acuity 계정을 나란히 지원하며, 도구 호출 시마다 전환 가능합니다.

유지 관리되는 무료 Acuity MCP가 없어서 직접 구축했습니다 — 연구 중 발견된 유일한 GitHub 저장소는 게시되지 않은 npm 패키지를 가리키고 있었습니다. @modelcontextprotocol/sdk + zod를 사용하며, stdio를 통해 실행됩니다.

Claude 사용자: 먼저 읽어주세요

사용자가 이 설정을 요청하거나, Acuity 계정 추가, 계정 전환, 연결 문제 해결을 요청하면 이 저장소의 **.claude/skills/acuity-mcp-setup/SKILL.md**를 로드하세요 — 모든 과정에 대한 전체 단계별 안내가 있습니다. 이 README는 사람을 위한 참고 자료이며, 스킬이 실제로 따라야 할 내용입니다.

설정 전 필요한 것

Acuity에서 Acuity Scheduling 사용자 ID와 API 키가 필요합니다: 비즈니스 설정 → 통합 → API. 연결하려는 각 Acuity 계정마다 한 쌍씩 필요합니다.

⚠️ Acuity는 요금제에 따라 API 액세스를 제한합니다. 일부 요금제에서는 모든 요청에 대해 403: API access is only available on Powerhouse plans를 반환합니다 — 이는 여기의 버그가 아니라 Acuity가 계정을 거부하는 것입니다. 기본 인증은 성공하지만(401 없음) 모든 호출이 여전히 403을 반환하는 것이 이 현상의 특징입니다. 이 문제가 발생하면 요금제를 업그레이드하거나 동일한 계정에 대한 대체 경로(예: 경험적으로 동일한 제한을 받지 않은 Zapier Acuity 커넥터)를 사용하세요.

설치

npm install

빠른 시작 — 하나의 계정

node bin/acuity-accounts.js add production --user-id <your-user-id> --api-key <your-api-key>

추가하는 첫 번째 계정이 자동으로 기본값이 됩니다. 그런 다음 Claude Code에 서버를 등록하세요:

claude mcp add acuity -s user -- node "$(pwd)/server.js"

새로운 Claude Code 세션을 시작하거나(또는 기존 세션에서 /mcp 실행) 도구가 나타나도록 하세요.

Claude 세션 없이도 작동하는지 확인하세요:

node bin/acuity-accounts.js test

여러 계정

원하는 만큼 이름이 있는 계정을 추가하세요:

node bin/acuity-accounts.js add production --user-id 1111111 --api-key aaaa... --label "Real account"
node bin/acuity-accounts.js add sandbox    --user-id 2222222 --api-key bbbb... --label "Trial/test account"

자격 증명은 ~/.config/acuity-mcp/accounts.json에 저장됩니다 (chmod 600, 이 저장소 내부에 절대 두지 않으며, 절대 커밋하지 않습니다). 관리 방법:

node bin/acuity-accounts.js list                # see configured accounts (never prints API keys)
node bin/acuity-accounts.js set-default sandbox # change which one is used by default
node bin/acuity-accounts.js remove sandbox      # remove one
node bin/acuity-accounts.js test sandbox        # verify one specific account's credentials

Claude 세션 내에서 계정 전환은 다시 등록할 필요가 없습니다 — 이 서버가 노출하는 모든 도구는 선택적 account 인수를 허용합니다:

"샌드박스 계정의 약속 유형 목록 보기" → Claude가 {"account": "sandbox"}와 함께 list_appointment_types를 호출합니다.

언제든지 Claude에게 list_accounts를 실행하도록 요청하여 구성된 계정과 기본값을 확인하세요.

대신 계정별로 완전히 분리된 MCP 서버 등록을 실행하려는 경우(예: 각각 고유한 이름의 서버로 표시되도록)에도 작동합니다 — 호출 시 account를 전달하는 대신 ACUITY_ACCOUNT를 이름으로 지정하세요:

claude mcp add acuity-production -s user -e ACUITY_ACCOUNT=production -- node "$(pwd)/server.js"
claude mcp add acuity-sandbox    -s user -e ACUITY_ACCOUNT=sandbox    -- node "$(pwd)/server.js"

자격 증명 확인 순서

1. ACUITY_USER_ID + ACUITY_API_KEY 환경 변수 (직접 재정의, 계정 파일 불필요)

2. 도구 호출 시 account 인수 또는 ACUITY_ACCOUNT 환경 변수 — 이름으로 조회

3. accounts.json 자체의 default 계정

4. 정확히 하나의 계정이 구성된 accounts.json — 자동으로 사용

5. 레거시 플랫 ~/.config/acuity-mcp/credentials 파일 (ACUITY_USER_ID=.../ACUITY_API_KEY=... 줄) — 이전 단일 계정 설정과의 하위 호환성을 위해 지원

도구

로컬 전용, Acuity API 호출 없음:

• list_accounts — 구성된 계정 이름/레이블 및 기본값 나열 (API 키는 절대 표시하지 않음)

읽기 전용:

• list_appointment_types — 예약 가능한 상담 유형 목록

• list_calendars — 캘린더/직원 목록

• list_appointments — 날짜 범위/캘린더/유형/취소 상태로 필터 가능

• get_appointment — ID로 특정 약속의 전체 세부 정보

• check_availability_dates — 약속 유형에 대한 한 달의 가능한 날짜

• check_availability_times — 약속 유형에 대한 특정 날짜의 가능한 시간 슬롯

• list_clients — 약속을 예약한 클라이언트

변경 (실제 캘린더에 실제 변경 — Claude는 호출 전에 확인을 요청합니다):

• create_appointment — 새 약속 예약

• reschedule_appointment — 약속의 날짜/시간 변경

• cancel_appointment — 약속 취소

모든 도구는 선택적 account 인수를 허용합니다 (여러 계정 참조).

구현되지 않음 (동일한 패턴, 필요시 나중에 추가): 결제, 블록, 양식, 웹훅, 기프트 인증서.

배운 점 (이 서버를 확장하기 전에 읽어보세요)

• 변경 호출에서 200 OK가 반환되었다고 해서 변경이 발생한 것은 아닙니다. reschedule_appointment는 원래 PUT /appointments/:id를 호출했는데, 이는 200을 반환하고 변경되지 않은 약속을 다시 반환했습니다 — Acuity는 해당 엔드포인트에서 datetime 필드를 조용히 무시했습니다. 수정 방법은 cancel_appointment가 이미 사용한 패턴(/appointments/:id/cancel)과 일치하는 전용 PUT /appointments/:id/reschedule 경로를 사용하는 것이었습니다. 쓰기 후에는 항상 get_appointment로 다시 가져와서 신뢰하기 전에 확인하세요, 특히 나중에 추가되는 새로운 변경 도구의 경우.

• npx @modelcontextprotocol/inspector --cli는 생성하는 node server.js 프로세스에 임시 환경 변수를 안정적으로 전달하지 않습니다. 이미 확인된 기본값이 아닌 자격 증명을 테스트하는 경우(예: ACUITY_USER_ID=x ACUITY_API_KEY=y npx @modelcontextprotocol/inspector --cli ...), 이미 구성된 값으로 조용히 대체되어 위양성/위음성을 줄 수 있습니다. 대신 node bin/acuity-accounts.js test <name>을 사용하세요 — 이 함정을 피하기 위해 특별히 제작되었습니다. 인스펙터 CLI는 원래 목적(확인된 기본 자격 증명 테스트 또는 --method tools/list로 도구 스키마 확인)에는 여전히 적합합니다.

수동 확인

node bin/acuity-accounts.js test            # tests the default/env-resolved account
node bin/acuity-accounts.js test <name>     # tests one specific named account
npx @modelcontextprotocol/inspector --cli node server.js --method tools/list   # confirms the server starts and tools register correctly