内容
# @oktopeak/intakeq-mcp
> ### 由 [Oktopeak](https://oktopeak.com/?utm_source=github&utm_medium=readme&utm_campaign=intakeq-mcp&utm_content=top-byline) 构建 — 面向医疗保健实践的 AI 转换和自动化
> **面向医疗和法律业务的数字化转型。** 我们构建 AI 集成、工作流自动化和您实践拥有的定制软件 — 包括此连接器。 → [预订 30 分钟通话](https://calendly.com/office-oktopeak/30min?utm_source=github&utm_medium=readme&utm_campaign=intakeq-mcp&utm_content=top-byline-call)
IntakeQ/PracticeQ 的 MCP 连接器，适用于 Claude。通过 [模型上下文协议](https://modelcontextprotocol.io/)，Claude 可以访问您的 IntakeQ 调度、入院表格、治疗记录、发票和客户记录。
每次 PHI 读取和写入都本地记录，符合 HIPAA §164.312(b)。
---
## ⚠️ 连接到真实患者数据之前
在连接器处理 PHI 之前，必须具备两项条件：
1. **IntakeQ BAA** — IntakeQ/PracticeQ 包含业务关联协议。在上线前，在您的 IntakeQ 账户（设置 → HIPAA）中签署它。这是 IntakeQ 的优势之一：BAA 是自助服务且包含在所有计划中。
2. **Anthropic 企业级，启用 ZDR** — 使用托管 Claude + MCP 时，PHI 会发送到 Anthropic 进行推理。可防御的声明是 **禁用训练 + 企业级零数据保留 + BAA** — 而不是数据本地性。“访问”（模型处理它）是暴露，而不仅仅是保留。
在与真实患者一起使用此功能之前，请注册 Anthropic 企业级并请求 BAA。
**此连接器的功能：**
- 代理 IntakeQ REST API 的身份验证调用
- 每条 PHI 读取和写入记录到 `~/.intakeq-mcp/audit.log`（HIPAA §164.312(b)）
- 在本地加密存储您的 API 密钥（AES-256-GCM）— 不存储 PHI 内容（审计条目仅包含访问轨迹标识符）
---
## 安装
```bash
npm install -g @oktopeak/intakeq-mcp
```
## Claude 桌面配置
```json
{
"mcpServers": {
"intakeq": {
"command": "intakeq-mcp"
}
}
}
```
## 身份验证
在 IntakeQ 中生成您的 API 密钥：**设置 → 集成 → 开发者 API**
然后告诉 Claude：
> “将我的 IntakeQ API 密钥设置为 [您的密钥]”
或直接使用 MCP 工具：`set_api_key`
## 工具
| 工具 | 描述 | 读写 |
|------|-------------|-----|
| `set_api_key` | 存储 IntakeQ API 密钥 | 写 |
| `auth_status` | 验证 API 连接 | 读 |
| `clear_api_key` | 删除存储的密钥 | 写 |
| `list_clients` | 搜索/列出客户 | 读 |
| `get_client` | 单个客户资料 | 读 |
| `list_practitioners` | 账户中的所有执业者 | 读 |
| `list_services` | 账户中配置的服务 | 读 |
| `list_locations` | 账户中配置的位置 | 读 |
| `list_appointments` | 按客户/日期排列的预约 | 读 |
| `get_appointment` | 单个预约 | 读 |
| `create_appointment` | 预订预约 | 写 |
| `update_appointment` | 重新安排/更新 | 写 |
| `list_intake_forms` | 已提交的入院表格 | 读 |
| `get_form` | 完整的表格及答案 | 读 |
| `list_questionnaire_templates` | 可用的表格模板 | 读 |
| `send_intake_form` | 向客户发送表格 | 写 |
| `list_notes` | 治疗记录（IntakeQ API 中只读） | 读 |
| `get_note` | 完整的记录 | 读 |
| `list_invoices` | 客户发票 | 读 |
| `get_invoice` | 单个发票 | 读 |
| `list_files` | 客户文件元数据 | 读 |
| `audit_export` | 导出 HIPAA 审计轨迹 | 读 |
> **提示：** 在 `create_appointment` 之前调用 `list_practitioners`、`list_services` 和 `list_locations` 以获取有效的 ID。
## MCP 资源
| 资源 URI | 描述 |
|---|---|
| `intakeq://compliance-notice` | HIPAA 合规通知 — BAA 要求和连接器记录内容 |
| `intakeq://auth-status` | 实时身份验证状态（JSON） |
## HIPAA 审计日志
每次 PHI 读取和写入都会追加到 `~/.intakeq-mcp/audit.log`（JSONL 格式）。
每个条目记录：时间戳、会话 ID、机器 IP、工具名称、参数（已净化）、结果、执业者 ID、客户 ID 和结果计数。
在任何时候导出审计日志：要求 Claude 运行 `audit_export`。
**审计日志是 fail-open 的。** 如果日志文件无法写入（磁盘已满、权限问题），工具调用仍会完成，而不是阻止临床工作 — 失败信息会以 `[audit-log-failure]` 前缀写入 stderr，以便监控/提醒。如果您需要确保 PHI 访问不会留下未记录的日志，请在部署中监控进程 stderr 中的该前缀。
## HTTP 传输
服务器默认以 **stdio 模式** 运行。要作为 HTTP 服务器运行（例如，用于多用户或远程部署）：
```bash
MCP_API_KEY=your-secret TRANSPORT=http PORT=3000 intakeq-mcp
```
MCP 端点位于 `/mcp`，需要 Bearer 令牌（`MCP_API_KEY`）验证。**服务器拒绝在未设置 `MCP_API_KEY` 的情况下以 HTTP 模式启动**，因为未经身份验证的端点将使任何可以访问端口的人都能访问每个 PHI 工具。要明确选择本地开发的无身份验证端点，请设置 `MCP_ALLOW_NO_AUTH=true` — 绝不能使用真实患者数据。
HTTP 传输本身不终止 TLS。请在反向代理（nginx、Caddy、云提供商的负载均衡器等）后面运行它，以终止 HTTPS — 否则，Bearer 令牌和所有 PHI 在传输过程中都会以明文发送到网络上。
每个 HTTP 会话都维护自己的内存中的 API 密钥 — `set_api_key` 工具将密钥限定在会话范围内，从不写入共享磁盘文件。会话在 24 小时后被垃圾回收。
健康检查：`GET /health` → `{ "ok": true, "sessions": <count> }`
## 环境变量
| 变量 | 默认值 | 描述 |
|---|---|---|
| `INTAKEQ_API_KEY` | — | CI / 无头使用的备用 API 密钥（优先使用 `set_api_key` 工具） |
| `INTAKEQ_API_BASE` | `https://intakeq.com/api/v1` | 重写 IntakeQ API 基本 URL |
| `TRANSPORT` | `stdio` | 传输模式：`stdio` 或 `http` |
| `PORT` | `3000` | HTTP 服务器端口（仅 HTTP 模式） |
| `MCP_BASE_URL` | `http://127.0.0.1:3000` | HTTP 启动日志中打印的基本 URL |
| `MCP_API_KEY` | — | 验证 HTTP `/mcp` 端点的 Bearer 令牌。**在 HTTP 模式下需要**，除非 `MCP_ALLOW_NO_AUTH=true` |
| `MCP_ALLOW_NO_AUTH` | — | 设置为 `true` 以明确允许 HTTP 模式下不使用 `MCP_API_KEY`（仅限本地开发） |
## 速率限制
IntakeQ 强制执行约 10 次请求/分钟。连接器在 HTTP 429 时自动重试（最多 3 次尝试，延迟分别为 10 秒、20 秒和 30 秒）。3 次失败后，错误被抛出，而不是无限期挂起。
## 尚未涵盖
- 保险理赔 / CMS-1500 编写
- Webhooks
- 批量操作
- 创建治疗记录（IntakeQ API 中不可用）
## Oktopeak 的其他开源连接器
相同的架构（加密密钥存储、审计日志、速率限制），不同的平台：
- **[Clio MCP](https://github.com/oktopeak/clio-mcp)** — Claude + Clio 实践管理（`@oktopeak/clio-mcp`）
- **[MyCase MCP](https://github.com/oktopeak/mycase-mcp)** — Claude + MyCase 法律实践管理（`@oktopeak/mycase-mcp`）
- **[Filevine MCP](https://github.com/oktopeak/filevine-mcp)** — Claude + Filevine 实践管理（`@oktopeak/filevine-mcp`）
## 支持该项目
此连接器是免费的，MIT 许可，并由 [Oktopeak](https://oktopeak.com) 维护。它将始终如此 — 我们不接受捐款。如果它为您节省了时间，以下是真正有帮助的事情：
- **给此仓库加星。** 这确实是其他公司找到它的方式。
- **告诉另一家运行 IntakeQ 的公司。**
- **如果我们直接帮助了您，请留下评论](https://clutch.co/profile/oktopeak)**。
- 需要为您的公司部署、扩展或维护此连接器？ **[商业支持](https://oktopeak.com/services/healthcare-ai-integration/)** — 这就是我们资助免费工作的资金来源。
## 关于我们
**[Oktopeak](https://oktopeak.com/?utm_source=github&utm_medium=readme&utm_campaign=intakeq-mcp&utm_content=who-we-are) — 面向医疗和法律公司的数字化转型。**
我们是一个 7 人组成的内部产品团队，为受监管的行业构建 AI 解决方案：AI 集成、工作流自动化和客户完全拥有的定制软件。我们维护四个开源 MCP 连接器 — [Clio](https://github.com/oktopeak/clio-mcp)、[MyCase](https://github.com/oktopeak/mycase-mcp)、[Filevine](https://github.com/oktopeak/filevine-mcp) 和 IntakeQ — 并在具有作用域凭证、审计日志和围绕您的团队实际工作的工作流的真实实践中部署它们。
- 🌐 [oktopeak.com](https://oktopeak.com/?utm_source=github&utm_medium=readme&utm_campaign=intakeq-mcp&utm_content=who-we-are)
- 📅 [预订 30 分钟通话](https://calendly.com/office-oktopeak/30min?utm_source=github&utm_medium=readme&utm_campaign=intakeq-mcp&utm_content=who-we-are-call)
- ✉️ office@oktopeak.com — 欢迎安全报告
- 💼 [LinkedIn](https://www.linkedin.com/company/oktopeak-tech)
