simplepractice-mcp

用于 SimplePractice 客户门户 的 MCP 服务器 —— 即诊所的 客户 登录的那一侧，而非临床医生侧。通过门户自身的 JSON:API 读取预约、账单、文书和公告。

由 AI（Claude Code）开发和维护。请自行斟酌使用。

它能读取什么

所有操作均为只读。取消、签署和支付均在门户中完成。

Related MCP server: practice-fusion-mcp

设置

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

SIMPLEPRACTICE_PRACTICE 是诊所的门户地址 —— 即您提供商通过电子邮件发送的链接中的 slug 或完整的 <practice>.clientsecure.me 主机名。

登录

客户门户 没有密码。SimplePractice 会通过电子邮件发送一次性链接（或 6 位 PIN 码）；您将其兑换为会话 cookie：

1. simplepractice_request_sign_in_link { email, confirm: true }

2. 打开电子邮件，复制链接。

3. simplepractice_verify_sign_in_token { link } —— 传递整个链接；令牌是其 # 片段，工具会自动提取。

链接为一次性使用 —— 重放会返回 401 "Authorization has already been used or expired" —— 且有效期为 24 小时。请求端点按地址 和 IP 进行速率限制，这就是发送需要确认的原因：重试循环会将您锁在唯一的入口之外。没有刷新令牌；当会话过期时，您需要重新登录。

整个链路已针对真实门户进行端到端验证 —— 请求、电子邮件中的链接、返回 verified 及会话 cookie 的交换，以及使用新会话进行的经过身份验证的读取。

由于该流程仅需 HTTP 和您的收件箱，此服务器没有浏览器依赖，可在任何地方运行。

不使用服务器

skills/simplepractice-fpx 使用 curl 执行相同的读取，既可以通过魔法链接登录，也可以使用 fpx 从浏览器标签页中提取会话 cookie。

构建笔记

门户是一个 Ember 应用，附带 公开的 sourcemap，因此其模型、适配器和路由可直接读取 —— docs/SIMPLEPRACTICE-API.md 记录了端点和陷阱，所有内容均已在真实门户上确认：

• SPA 的 catch-all 对 API 未定义的任何路径返回 HTTP 200 且内容类型为 text/html。/cards 和 /client-billing-overviews 看起来像可用的空端点，但实际上根本不是端点 —— 两者都是 /clients/<id> 的 include 关系。

• hasDocumentPdf、卡片的 isDefault 以及客户的 permissions 数据块都是 字符串，而非布尔值或对象。

• 账单按 游标 分页（page[before] = 行的 cursorId），预约按 数字 分页。两者不可互换。

开发

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

许可证

MIT