acuity-mcp

Ein lokaler MCP-Server, der die Acuity Scheduling API als Claude-Code-Tools bereitstellt – Termine auflisten/erstellen/verschieben/stornieren, Verfügbarkeit prüfen, Termintypen, Kalender und Kunden auflisten, alles direkt aus einer Claude-Sitzung. Unterstützt mehrere Acuity-Konten nebeneinander, pro Tool-Aufruf umschaltbar.

Eigens entwickelt, weil es keinen gepflegten kostenlosen MCP für Acuity gibt – das einzige GitHub-Repo, das während der Recherche gefunden wurde, verwies auf ein npm-Paket, das nie veröffentlicht wurde. Verwendet @modelcontextprotocol/sdk + zod, läuft über stdio.

Wenn du Claude bist: lies zuerst dies

Wenn ein Benutzer dich bittet, dies einzurichten, ein Acuity-Konto hinzuzufügen, Konten zu wechseln oder eine Verbindung zu beheben, lade .claude/skills/acuity-mcp-setup/SKILL.md in diesem Repo – es enthält die vollständige Schritt-für-Schritt-Anleitung für all das. Diese README ist die Referenz für Menschen; der Skill ist das, was du tatsächlich befolgen solltest.

Was du vor der Einrichtung brauchst

Eine Acuity Scheduling User ID und einen API-Schlüssel aus Acuity: Business Settings → Integrations → API. Ein Paar pro Acuity-Konto, das du verbinden möchtest.

⚠️ Acuity beschränkt den API-Zugriff je nach Tarifstufe. Manche Tarife geben bei jeder Anfrage 403: API access is only available on Powerhouse plans zurück – das ist die Ablehnung deines Kontos durch Acuity, kein Fehler hier. Wenn die Basisauthentifizierung erfolgreich ist (kein 401), aber jeder Aufruf weiterhin 403 liefert, ist das ein Zeichen dafür. Falls du darauf triffst, entweder den Tarif upgraden oder einen alternativen Weg zum selben Konto nutzen (z. B. einen Zapier-Acuity-Connector, der nachweislich nicht derselben Einschränkung unterliegt).

Installation

npm install

Schnellstart — ein Konto

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

Das erste Konto, das du hinzufügst, wird automatisch zum Standard. Dann registrierst du den Server bei Claude Code:

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

Starte eine neue Claude-Code-Sitzung (oder führe /mcp in einer bestehenden aus), damit die Tools angezeigt werden.

Überprüfe, ob es ganz ohne Claude-Sitzung funktioniert:

node bin/acuity-accounts.js test

Mehrere Konten

Füge so viele benannte Konten hinzu, wie du möchtest:

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"

Die Anmeldedaten liegen in ~/.config/acuity-mcp/accounts.json (chmod 600, niemals in diesem Repo, niemals eingecheckt). Verwalte sie:

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

Das Wechseln von Konten innerhalb einer Claude-Sitzung erfordert keine erneute Registrierung – jedes Tool, das dieser Server bereitstellt, akzeptiert ein optionales account-Argument:

„Liste die Termintypen für das Sandbox-Konto auf“ → Claude ruft list_appointment_types mit {"account": "sandbox"} auf.

Bitte Claude jederzeit, list_accounts auszuführen, um zu sehen, was konfiguriert ist und welches Konto das Standard ist.

Wenn du stattdessen vollständig getrennte MCP-Serverregistrierungen pro Konto ausführen möchtest (z. B. damit jedes als ein Server mit eindeutigem Namen erscheint), funktioniert das weiterhin – setze ACUITY_ACCOUNT auf einen Namen, anstatt account pro Aufruf zu übergeben:

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"

Auflösungsreihenfolge der Anmeldedaten

1. ACUITY_USER_ID + ACUITY_API_KEY Umgebungsvariablen (direkte Überschreibung, keine Kontendatei erforderlich)

2. account-Argument bei einem Tool-Aufruf oder die Umgebungsvariable ACUITY_ACCOUNT – nach Namen gesucht

3. Das eigene default-Konto in accounts.json

4. accounts.json mit genau einem konfigurierten Konto – wird automatisch verwendet

5. Legacy-Flachdatei ~/.config/acuity-mcp/credentials (Zeilen ACUITY_USER_ID=.../ACUITY_API_KEY=...) – aus Kompatibilitätsgründen mit älteren Ein-Konto-Setups unterstützt

Tools

Nur lokal, kein Acuity-API-Aufruf:

• list_accounts — listet konfigurierte Kontonamen/-bezeichnungen und das Standardkonto auf (niemals API-Schlüssel)

Schreibgeschützt:

• list_appointment_types — listet buchbare Beratungstypen auf

• list_calendars — listet Kalender/Mitarbeiter auf

• list_appointments — filterbar nach Datumsbereich / Kalender / Typ / Stornierungsstatus

• get_appointment — vollständige Details zu einem Termin anhand der ID

• check_availability_dates — verfügbare Tage in einem Monat für einen Termintyp

• check_availability_times — verfügbare Zeitfenster an einem Datum für einen Termintyp

• list_clients — Kunden, die Termine gebucht haben

Verändernd (echte Änderungen am Live-Kalender – Claude wird vor dem Aufruf dieser Funktionen um Bestätigung bitten):

• create_appointment — einen neuen Termin buchen

• reschedule_appointment — Datum/Uhrzeit eines Termins ändern

• cancel_appointment — einen Termin stornieren

Alle Tools akzeptieren ein optionales account-Argument (siehe Mehrere Konten).

Nicht implementiert (gleiches Muster, später bei Bedarf hinzufügen): Zahlungen, Blocks, Formulare, Webhooks, Geschenkgutscheine.

Erkenntnisse (vor der Erweiterung dieses Servers lesen)

• Ein 200 OK von einem verändernden Aufruf beweist nicht, dass die Änderung stattgefunden hat. reschedule_appointment rief ursprünglich PUT /appointments/:id auf, was 200 zurückgab und den unveränderten Termin zurückspiegelte – Acuity ignorierte das Feld datetime an diesem Endpunkt stillschweigend. Die Lösung war die dedizierte Route PUT /appointments/:id/reschedule, die dem Muster von cancel_appointment folgt, das bereits /appointments/:id/cancel verwendet. Hole nach einem Schreibvorgang immer erneut mit get_appointment ab, bevor du ihm vertraust, insbesondere bei jedem neuen verändernden Tool, das später hinzugefügt wird.

• npx @modelcontextprotocol/inspector --cli leitet Ad-hoc-Umgebungsvariablen nicht zuverlässig an den node server.js-Prozess weiter, den es startet. Wenn du Anmeldedaten testest, die nicht bereits die aufgelösten Standardwerte sind (z. B. ACUITY_USER_ID=x ACUITY_API_KEY=y npx @modelcontextprotocol/inspector --cli ...), kann es stillschweigend auf das bereits Konfigurierte zurückfallen und ein falsches Positiv/Negativ-Ergebnis liefern. Verwende stattdessen node bin/acuity-accounts.js test <name> – es wurde speziell entwickelt, um diese Falle zu vermeiden. Die Inspector-CLI bleibt für ihren ursprünglichen Zweck gut geeignet: das Testen der aufgelösten Standard-Anmeldedaten oder --method tools/list zur Überprüfung der Tool-Schemas.

Manuelle Überprüfung

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