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 の Business Settings → Integrations → API から取得する Acuity Scheduling User ID と API Key が必要です。接続する Acuity アカウントごとに 1 組必要です。

⚠️ Acuity はプラン階層によって API アクセスを制限しています。 一部のプランでは、すべてのリクエストに対して 403: API access is only available on Powerhouse plans が返されます。これはアカウントが Acuity に拒否されているだけで、こちらのバグではありません。Basic Auth が成功し（401 が返らず）、それでもすべての呼び出しで 403 が返される場合は、これが典型的な症状です。該当する場合は、プランをアップグレードするか、同じアカウントへの代替経路（例: Zapier Acuity コネクタ。実際に同じ制限を受けていないことが確認されています）を使用してください。

インストール

npm install

クイックスタート — 1 アカウント

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 は list_appointment_types を {"account": "sandbox"} で呼び出します。

いつでも 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 環境変数（直接上書き。accounts ファイルは不要）

2. ツール呼び出しの account 引数、または ACUITY_ACCOUNT 環境変数 — 名前で検索

3. accounts.json 内の default アカウント

4. accounts.json にアカウントが 1 つだけ設定されている場合 — 自動的に使用

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 による 1 件の予約の完全な詳細

• 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 フィールドを黙って無視していました。修正は、専用の PUT /appointments/:id/reschedule ルートで、cancel_appointment がすでに使用していたパターン（/appointments/:id/cancel）に合わせたものでした。書き込み後は、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