simplepractice-mcp

Name: simplepractice-mcp
Author: chrischall

本地服务

github.com/chrischall健康医疗02 天前更新

代码仓库

关于 simplepractice-mcp

simplepractice-mcp 是面向 SimplePractice Client Portal 客户的只读 MCP 服务，可查看预约、账单、文件请求、共享文件和公告。它通过邮件一次性链接或 PIN 登录，不依赖浏览器。

主要功能

01查看预约及诊疗地点
02读取账单、余额和付款方式
03查看文件请求与共享文件
04读取诊所公告和未读数量
05通过邮件链接或 PIN 登录

适用场景

01查看预约时间及诊疗人员
02核对账单、余额和收据
03查看待完成的文书请求与诊所公告
04使用邮件登录链接建立门户会话

MCP 相关

该 MCP 服务向客户端提供 SimplePractice Client Portal 的只读查询工具，以及会话登录管理工具。取消预约、签署文件和付款需在门户中完成。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "chrischall-simplepractice": {
      "command": "npx",
      "args": [
        "-y",
        "simplepractice-mcp"
      ],
      "env": {
        "SIMPLEPRACTICE_PRACTICE": "<SIMPLEPRACTICE_PRACTICE>",
        "SIMPLEPRACTICE_SESSION_FILE": "<SIMPLEPRACTICE_SESSION_FILE>"
      }
    }
  }
}

启动命令npx -y simplepractice-mcp

需要配置的环境变量

SIMPLEPRACTICE_PRACTICEOptional. Pins the server to one practice — the slug ("achievebalancetherapy") or the full host. Unset, the practice comes from your emailed sign-in link.

SIMPLEPRACTICE_SESSION_FILEWhere to persist the signed-in session (default ~/.simplepractice-mcp/session.json, written 0600).

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npmsimplepractice-mcp1.2.7stdio

工具

收录的工具列表 · 更新于 2 周前

此工具无需参数。

详细介绍

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`	已保存的卡片——品牌、末四位、有效期
`simplepractice_list_document_requests`	发给你的文书，可筛选仅显示未完成项
`simplepractice_get_document_request`	单项完整请求，含问题和答案
`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 特意不接受此参数：它返回的是文件引用，共享扫描件为 .jpg。

设置

npm install -g simplepractice-mcp

无需进行任何配置。诊所信息取自你的登录链接。

变量
`SIMPLEPRACTICE_PRACTICE`	可选——将服务固定到一家诊所（slug 或主机名）
`SIMPLEPRACTICE_SESSION_FILE`	可选——会话文件路径（默认 `~/.simplepractice-mcp/session.json`，权限设为 `0600`）

链接格式为 https://<practice>.clientsecure.me/sign-in/token#<TOKEN>，因此一次粘贴就包含了服务端所需的信息：令牌位于 # 片段中，主机名则标明了诊所。没有任何内容被硬编码，保存的会话会记住诊所，以供之后每次运行使用 — simplepractice_session_status 会报告当前使用的是哪家诊所，以及诊所信息来自链接、环境变量还是已保存的会话。

如需重新发送新链接，而不是使用已有链接，请指定一次诊所：

simplepractice_request_sign_in_link { email, practice: "achievebalancetherapy" }

发送前会要求你确认（参见确认）。

如果服务端已经知道诊所 — 来自之前的登录，或 SIMPLEPRACTICE_PRACTICE — 则可以省略 practice。

以下两种登录链接未指定诊所，会回退到已知的诊所：SimplePractice 发送的移动应用变体链接（https://clientsecure.me/client-portal-api/sign-in/token#<TOKEN>，指向裸域名），以及不带链接、直接粘贴的裸令牌。任何不属于 *.clientsecure.me 的主机上的链接都不会被采用 — 令牌不会发送到那里。

链接只能使用一次 — 重放链接会返回 401 "Authorization has already been used or expired" — 有效期为 24 小时。请求端点会按地址和 IP 限流，因此发送前会要求确认：重试循环可能会让你无法通过唯一的登录方式进入。没有刷新令牌；会话失效后，你需要重新登录。

simplepractice_sign_out 只会忘记存储在这台机器上的会话（即 session.json 中的条目）。不会通知 SimplePractice，因此会话令牌在 SimplePractice 端会一直有效，直到在那里过期 — 该令牌的任何副本（~/.simplepractice-mcp 的备份，或此服务的另一个运行实例）在此之前都能继续使用。有效期由 SimplePractice 决定；上文提到的 24 小时是登录链接的有效期，而非会话的有效期。它不会将你从其他位置的 Client Portal 登出，例如浏览器或应用。

整个流程已通过实时门户端到端验证 — 包括请求、通过电子邮件发送的链接、返回 verified 和会话 Cookie 的兑换操作，以及使用新会话进行的经过身份验证的读取操作。

由于此流程只需要 HTTP 和你的邮箱，此服务不依赖浏览器，可在任何地方运行。

确认

simplepractice_request_sign_in_link 会发送真实邮件，因此会先请求确认。在能够显示确认提示的客户端（Claude Code）上，你会看到提示，除非 MCP_CONFIRM_ELICITATION=off。在不能显示提示的客户端（claude.ai、Claude Desktop）上，首次调用不会发送邮件，而是返回预览信息——地址、诊所——以及一个 confirmToken；只有再次使用该令牌和相同参数调用，才会发送邮件。令牌只能使用一次，地址或诊所发生变化时请求会被拒绝。

变量	默认值
`MCP_CONFIRM_MODE`	`ask-user`	在无法显示确认提示的客户端（claude.ai、Claude Desktop）上，写入操作的处理方式。`ask-user`：分两步操作——首次调用不执行任何操作，只返回预览信息和令牌；模型必须先在聊天中获得你的批准，然后才能使用令牌再次调用。`auto`：同样分两步操作，但模型查看预览信息后可以自行使用令牌。`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 使用 curl 执行相同的读取操作，可以通过魔法链接登录，也可以使用 fpx 从浏览器标签页提取会话 Cookie。

构建过程中的注意事项

该门户是一个 Ember 应用，提供了公开的 sourcemap，因此可以直接读取其中的模型、适配器和路由——docs/SIMPLEPRACTICE-API.md 记录了端点和易踩的坑，且所有内容都已通过实时门户确认：

SPA 的兜底路由会针对 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              # 214 tests
npm run test:coverage # 100% enforced
npm run typecheck     # vitest does not run tsc — this does