simplepractice-mcp

simplepractice-mcp

SimplePractice Client Portal 向けの MCP サーバーです。診療所のクライアントがログインする側であり、臨床家側ではありません。予約、請求、書類、告知を、ポータル独自の JSON:API 経由で読み取ります。

AI（Claude Code）が開発・保守しています。ご自身の判断でご利用ください。

読み取れる内容

ツール	得られる情報
simplepractice_get_account	診療所、現在のクライアント、このログインで対象となるすべてのクライアント、キャンセルポリシー、機能の権限
simplepractice_list_appointments	予定済みまたはリクエスト済みの予約。臨床家と場所も含みます
simplepractice_list_billing_items	請求書・明細書・スーパービル・領収書・アカウント履歴
simplepractice_get_billing_overview	未払い残高とカテゴリ別の件数
simplepractice_list_payment_methods	保存済みカードのブランド、下4桁、有効期限
simplepractice_list_document_requests	送付された書類。未処理のみのフィルターも指定できます
simplepractice_get_document_request	1件のリクエストの詳細。質問と回答も含みます
simplepractice_list_documents	診療所が共有したファイル
simplepractice_list_announcements	診療所からのお知らせと未読件数
simplepractice_session_status · _request_sign_in_link · _verify_sign_in_token · _verify_sign_in_pin · _sign_out	サインイン
simplepractice_healthcheck	認証情報と上流への接続を確認します。失敗は例外ではなくデータとして報告されます

すべて読み取り専用です。キャンセル、署名、支払いはポータルで行います。

SimplePractice のレコードそのものではなく、加工したデータを返す読み取り（予約、請求項目、請求概要、個別の書類リクエスト、お知らせ）では、view を指定できます。デフォルトは compact です。この場合、このサーバーで用意している簡易表示を返し、簡易表示がない場合はモデルから見えないロゴとアバターの URL を除外します。view: "full" を指定すると、レコードを変更せずに返します。 simplepractice_list_documents では意図的に view を受け付けません。返されるのはファイル参照で、共有されたスキャン画像は .jpg です。

セットアップ

npm install -g simplepractice-mcp

設定は不要です。診療所はサインインリンクから取得されます。

変数
SIMPLEPRACTICE_PRACTICE	任意 — サーバーを1つの診療所に固定します（スラッグまたはホスト）
SIMPLEPRACTICE_SESSION_FILE	任意 — セッションファイルのパス（デフォルトは ~/.simplepractice-mcp/session.json、権限 0600 で書き込み）

サインイン

クライアントポータルにはパスワードがありません。SimplePractice から届くワンタイムリンク（または6桁のPIN）を、セッション Cookie と引き換えます。

1. プロバイダーから届いたメールを開き、リンクをコピーします。
2. simplepractice_verify_sign_in_token { link } — リンク全体を渡します。

リンクは https://<practice>.clientsecure.me/sign-in/token#<TOKEN> という形式です。そのため、一度貼り付けるだけで、サーバーが必要とする2つの情報がそろいます。トークンは # フラグメントにあり、ホスト名から診療所が特定されます。ハードコードされた値はなく、保存されたセッションには、以降の実行で使用する診療所も記録されます。simplepractice_session_status では、どの診療所が対象か、またリンク、環境変数、保存済みセッションのどれに由来するかを確認できます。

手元にあるリンクではなく、新しいリンクを送ってもらうには、診療所を一度指定します。

simplepractice_request_sign_in_link { email, practice: "achievebalancetherapy" }

送信前に確認を求められます（確認を参照）。

サーバーがすでに診療所を把握している場合は、practice を省略できます。過去のサインイン、または SIMPLEPRACTICE_PRACTICE から把握している場合が該当します。

診療所が指定されていないサインインリンクは2種類あり、すでに把握している診療所にフォールバックします。1つは SimplePractice が送信するモバイルアプリ版（https://clientsecure.me/client-portal-api/sign-in/token#<TOKEN>。ルートドメインを参照します）、もう1つはリンクなしで貼り付けたトークンです。*.clientsecure.me 以外のホストにあるリンクは、決して採用されません。トークンがそのホストに送信されることもありません。

リンクは一度しか使用できず、再利用すると 401 "Authorization has already been used or expired" が返されます。有効期限は24時間です。リクエストエンドポイントにはアドレスおよびIPごとのレート制限があるため、送信前に確認を求めます。リトライループが発生すると、唯一のログイン手段が使えなくなるためです。リフレッシュトークンはありません。セッションの有効期限が切れたら、再度サインインしてください。

simplepractice_sign_out は、このマシンに保存されたセッション（session.json 内のエントリー）を削除するだけです。SimplePractice には通知されないため、セッショントークンは SimplePractice 側で有効期限が切れるまで有効です。トークンのコピー（~/.simplepractice-mcp のバックアップや、このサーバーを実行中の別のコピーなど）は、その時点まで引き続き使用できます。有効期間は SimplePractice が決定します。上記の24時間はサインインリンクの有効期間であり、セッションの有効期間ではありません。また、ブラウザーやアプリなど、ほかの場所でクライアントポータルからサインアウトすることもありません。

この一連の手順は、実際のポータルを使って、リクエスト、メールで届くリンク、verified とセッション Cookie を返すトークン交換、新しいセッションでの認証済み読み取りまで、エンドツーエンドで検証済みです。

この手順に必要なのは HTTP とメールの受信だけなので、このサーバーはブラウザーに依存せず、どこでも実行できます。

確認

simplepractice_request_sign_in_link は実際にメールを送信するため、事前に確認を求めます。確認プロンプトを表示できるクライアント（Claude Code）では、MCP_CONFIRM_ELICITATION=off に設定されていない限り、プロンプトが表示されます。表示できないクライアント（claude.ai、Claude Desktop）では、最初の呼び出しでは何も送信されず、メールアドレスとプラクティス、および confirmToken のプレビューが返されます。そのトークンを使い、同じ引数で再度呼び出した場合にのみ送信されます。トークンは一度だけ使用でき、メールアドレスまたはプラクティスが変更されると拒否されます。

variable	default
MCP_CONFIRM_MODE	ask-user	確認プロンプトを表示できないクライアント（claude.ai、Claude Desktop）で書き込み操作をどう扱うかを指定します。ask-user：2 段階で処理します。最初の呼び出しでは何も行わず、プレビューとトークンを返します。モデルは、トークンを使って再度呼び出す前に、チャットであなたの承認を得る必要があります。auto：同じく 2 段階で処理しますが、プレビューを確認したモデルがトークンを使用できます。refuse：そのようなクライアントでは書き込み操作を拒否します。プロンプトを表示できるクライアント（Claude Code）には、MCP_CONFIRM_ELICITATION=off に設定されていない限り、常に実際のプロンプトが表示されます。認識できない値は refuse として扱われます。
MCP_CONFIRM_ELICITATION	on	off にすると確認プロンプトは表示されず、すべてのクライアントで MCP_CONFIRM_MODE の手順が適用されます。プロンプトをサポートするとしているのに表示されないクライアント（書き込み操作が停止する場合があります — opencode 2.0.x）では、この値を設定してください。それ以外の値では on のままとなり、stderr に警告が出力されます。
MCP_CONFIRM_TTL_SECONDS	600	トークンの有効期間です。
MCP_CONFIRM_SECRET	プロセスごとにランダム	署名キーです。サーバー再起動後もトークンを有効にする必要がある場合にのみ設定してください。mcp-host では、ホストが子プロセスごとに安定したキー（MCP_HOST_CONFIRM_SECRET）を提供し、使用済みトークンは MCP_DATA_DIR 配下に記録されるため、アイドル状態からの再起動後も承認が保持されます。

サーバーを使わない場合

skills/simplepractice-fpx は、マジックリンクでサインインするか、ブラウザーのタブからセッション Cookie を取得する fpx を使って、同じ読み取り操作を行います。

実装時の注意点

このポータルは 公開 sourcemap を含む Ember アプリなので、モデル、アダプター、ルートを直接読むことができます。docs/SIMPLEPRACTICE-API.md にはエンドポイントと注意点が記録されており、すべて実際のポータルで確認済みです。

• SPA のキャッチオールは、API で定義されていないパスに対して HTTP 200 と text/html を返します。/cards と /client-billing-overviews は機能している空のエンドポイントのように見えますが、どちらも実際にはエンドポイントではなく、/clients/<id> の include リレーションです。
• hasDocumentPdf、カードの isDefault、クライアントの permissions の値は、いずれもブール値やオブジェクトではなく 文字列 です。
• 請求ページは カーソル（page[before] = 行の cursorId）でページ分割され、予約は 番号 でページ分割されます。この 2 つは互換性がありません。

開発

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

ライセンス

MIT