simplepractice-mcp

MCP-Server für das SimplePractice Client Portal – die Seite, mit der sich die Klienten einer Praxis anmelden, nicht die Therapeutenseite. Termine, Abrechnung, Unterlagen und Ankündigungen, gelesen über die eigene JSON:API des Portals.

Entwickelt und gepflegt von KI (Claude Code). Verwendung auf eigene Verantwortung.

Was es liest

Alles ist schreibgeschützt. Stornieren, Unterschreiben und Bezahlen erfolgen im Portal.

Related MCP server: practice-fusion-mcp

Einrichtung

npm install -g simplepractice-mcp
export SIMPLEPRACTICE_PRACTICE=achievebalancetherapy   # or the full host

SIMPLEPRACTICE_PRACTICE ist die Portaladresse der Praxis – der Slug oder der gesamte <practice>.clientsecure.me-Host aus dem Link, den Ihr Anbieter per E-Mail gesendet hat.

Anmelden

Das Client Portal hat kein Passwort. SimplePractice sendet per E-Mail einen Einmal-Link (oder eine 6-stellige PIN); Sie tauschen ihn gegen ein Sitzungs-Cookie ein:

1. simplepractice_request_sign_in_link { email, confirm: true }

2. Öffnen Sie die E-Mail und kopieren Sie den Link.

3. simplepractice_verify_sign_in_token { link } – übergeben Sie den gesamten Link; das Token ist sein #-Fragment und das Tool extrahiert es.

Links sind nur einmal verwendbar – das erneute Senden eines Links führt zu 401 "Authorization has already been used or expired" – und sie sind 24 Stunden gültig. Der Anfrage-Endpunkt ist pro Adresse und pro IP ratenbegrenzt, weshalb das Senden bestätigungspflichtig ist: Eine Wiederholungsschleife sperrt Sie aus dem einzigen Zugang aus. Es gibt kein Refresh-Token; wenn die Sitzung abläuft, melden Sie sich erneut an.

Die gesamte Kette wird Ende-zu-Ende gegen ein Live-Portal verifiziert – Anfrage, der per E-Mail gesendete Link, der Austausch, der verified plus ein Sitzungs-Cookie zurückgibt, und ein authentifizierter Lesevorgang mit dieser neuen Sitzung.

Da dieser Ablauf nur HTTP und Ihr Postfach benötigt, hat dieser Server keine Browser-Abhängigkeit und kann überall ausgeführt werden.

Ohne den Server

skills/simplepractice-fpx führt dieselben Lesevorgänge mit curl durch, entweder per Magic-Link-Anmeldung oder durch Übernahme des Sitzungs-Cookies aus einem Browser-Tab mit fpx.

Anmerkungen zur Entwicklung

Das Portal ist eine Ember-App, die öffentliche Sourcemaps ausliefert, sodass ihre Modelle, Adapter und Routen direkt lesbar sind – docs/SIMPLEPRACTICE-API.md dokumentiert die Endpunkte und die Fallstricke, alle gegen ein Live-Portal bestätigt:

• Die SPA-Catch-all-Antwort liefert HTTP 200 mit text/html für jeden Pfad, den die API nicht definiert. /cards und /client-billing-overviews sehen wie funktionierende, leere Endpunkte aus und sind überhaupt keine Endpunkte – beide sind include-Beziehungen von /clients/<id>.

• hasDocumentPdf, das isDefault einer Karte und der permissions-Blob des Klienten sind alle Strings, keine Booleans oder Objekte.

• Abrechnung paginiert per Cursor (page[before] = die cursorId einer Zeile), Termine per Nummer. Die beiden sind nicht austauschbar.

Entwicklung

npm install
npm run build
npm test              # 151 tests
npm run test:coverage # 100% enforced
npm run typecheck     # vitest does not run tsc — this does

Lizenz

MIT