Tebra MCP Server

tebra mcp服务器

](https://www.npmjs.com/package/tebra-mcp-server) 

MCP服务器 文胸 （原名Kareo）从事管理工作。将您现有的Tebra帐户连接到Claude和其他MCP兼容的AI代理，暴露 33个SOAP工具 和 12个Contoso临床工具 用于患者、就诊、预约、账单、文件、保险和临床数据。没有有效的Tebra API证书，无法访问任何数据。

快速开始

npx tebra-mcp-server

先决条件

• Node.js 18+
• Tebra SOAP API凭据（在“设置”>“API”下的Tebra PM管理中生成）
• （可选）用于临床数据访问的Tebra FHIR API证书

环境变量

SOAP API（必需）

FHIR API（可选--启用12个临床数据工具）

FHIR证书可从Tebra开发人员门户网站API>FHIR访问获取。服务器使用带有自动令牌缓存和刷新的OAuth2客户端凭据流。

安装

克劳德代码

添加 .mcp.json 在项目根目录中：

{
  "mcpServers": {
    "tebra": {
      "command": "npx",
      "args": ["-y", "tebra-mcp-server"],
      "env": {
        "TEBRA_SOAP_USER": "user@practice.com",
        "TEBRA_SOAP_PASSWORD": "your-password",
        "TEBRA_CUSTOMER_KEY": "your-customer-key",
        "TEBRA_FHIR_CLIENT_ID": "optional-fhir-client-id",
        "TEBRA_FHIR_CLIENT_SECRET": "optional-fhir-client-secret"
      }
    }
  }
}

克劳德桌面

添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "tebra": {
      "command": "npx",
      "args": ["-y", "tebra-mcp-server"],
      "env": {
        "TEBRA_SOAP_USER": "user@practice.com",
        "TEBRA_SOAP_PASSWORD": "your-password",
        "TEBRA_CUSTOMER_KEY": "your-customer-key"
      }
    }
  }
}

光标/VS代码

添加到MCP设置中：

{
  "mcpServers": {
    "tebra": {
      "command": "npx",
      "args": ["-y", "tebra-mcp-server"],
      "env": {
        "TEBRA_SOAP_USER": "user@practice.com",
        "TEBRA_SOAP_PASSWORD": "your-password",
        "TEBRA_CUSTOMER_KEY": "your-customer-key"
      }
    }
  }
}

可用工具（共45个）

患者管理

预约

遭遇与账单

保险和授权

实践配置

文件

财务分析

外部供应商和系统

GetI临床数据（需要使用GetI证书）

这些工具通过Tebra FHIR R4 API访问临床数据。它们需要单独的Contoso证书（见上文环境变量）。如果未配置Contoso凭据，这些工具将不会被注册。

速率限制

SOAP客户端强制每个操作的调用间隔最小，反映了Tebra API技术指南中的节流阈值。当一个工具被调用的频率超过其限制允许的频率时，客户端会休眠足够长的时间来满足发送请求之前的间隔——调用会被延迟，永远不会被丢弃。

除了客户端限制之外，每个SOAP调用在出现错误之前都会以指数回退（1s、2s、4s）重试最多3次。使用 tebra_get_throttles 实时查询Tebra的服务器端速率限制计数器。

示例工作流

调度流程

1. tebra_get_providers          -- Get provider IDs
2. tebra_get_service_locations  -- Get location IDs
3. tebra_get_appointment_reasons -- Get reason/type IDs
4. tebra_create_appointment     -- Create with provider, location, reason IDs
5. tebra_get_appointment_detail -- Verify creation

遭遇审批流程

1. tebra_create_encounter            -- Create superbill (status: Draft)
2. tebra_update_encounter_status     -- Move to Review
3. tebra_update_encounter_status     -- Move to Approved (triggers billing)
   OR
3. tebra_update_encounter_status     -- Reject back to Draft with reason

付款过账流程

1. tebra_search_patients    -- Find patient
2. tebra_get_charges        -- Find outstanding charges
3. tebra_create_payment     -- Post payment to patient account
4. tebra_get_payments       -- Verify payment posted

患者入职培训（诱惑-md.com）

1. tebra_search_patients              -- Check for existing patient
2. tebra_create_patient               -- Create if not found
3. tebra_update_patient_external_id   -- Link Supabase client ID
4. tebra_create_appointment           -- Schedule first visit

注释创建的临床背景（EPIC注释）

1. tebra_get_appointments             -- Get today's schedule
2. tebra_get_appointment_detail       -- Get appointment context
3. tebra_get_patient                  -- Full patient demographics
4. tebra_get_patient_authorizations   -- Check auth status
5. tebra_fhir_get_allergies           -- Allergies
6. tebra_fhir_get_medications         -- Current medications
7. tebra_fhir_get_conditions          -- Problem list
8. tebra_fhir_get_vitals              -- Recent vitals

工具依赖链

某些工具需要从其他工具获得的ID。关键依赖关系：

tebra_create_appointment
  requires: providerId   (from tebra_get_providers)
  requires: locationId   (from tebra_get_service_locations)
  requires: reasonId     (from tebra_get_appointment_reasons)
  optional: patientId    (from tebra_search_patients or tebra_create_patient)

tebra_create_encounter
  requires: patientId    (from tebra_search_patients)
  requires: providerId   (from tebra_get_providers)
  optional: authId       (from tebra_get_patient_authorizations)

tebra_create_payment
  requires: patientId    (from tebra_search_patients)

tebra_update_encounter_status
  requires: encounterId  (from tebra_create_encounter or tebra_get_encounter)

tebra_create_document
  requires: patientId    (from tebra_search_patients)

tebra_update_patient_external_id
  requires: patientId    (from tebra_search_patients or tebra_create_patient)

All FHIR tools
  require: patientId     (from tebra_search_patients)

集成服务

预构建的集成模块可在 src/integrations/ 对于两个项目：

• epic-notes-integration.ts --安排预播种、创建笔记的约会上下文、将签名的笔记推回到Tebra。复制到您的EPIC Notes项目 src/lib/services/tebra-integration.ts.

• fal-integration.ts --患者从诱惑-md.com注册、条纹支付发布、Supabase到Tebra ID链接同步。复制到您的FAL项目 src/lib/services/tebra-integration.ts.

这两个模块都定义了 McpToolCaller 接口，并与任何MCP客户端实现配合使用。

api参考

服务器封装了两个Tebra API：

SOAP API v2.1 （33工具）

• 端点： https://webservice.kareo.com/services/soap/2.1/KareoServices.svc
• Auth:带有用户、密码和CustomerKey的请求标头
• 所有请求都包括指数回退的重试（1秒、2秒、4秒3次尝试）

FHIR R4 API （12个工具）

• 端点： https://fhir.kareo.com/r4 （可配置）
• Auth:OAuth2客户端凭据流
• 令牌缓存，到期前自动刷新

发展

git clone https://github.com/jamesrosing/tebra-mcp-server.git
cd tebra-mcp-server
npm install

npm run dev    # tsx — runs src/index.ts directly without a build step
npm run build  # tsc — compiles to dist/
npm test       # node:test via tsx — runs the SOAP client regression suite
npm start      # node dist/index.js — runs the compiled output

更新日志

0.2.5 (2026-04-28)

• 修复（肥皂）：现在每个GET请求体都包含一个兄弟 ` 之后 .Tebra的WSDL标记 Filter 作为 minOccurs="0"，但它们的服务器端 GetFilteredX(...) 方法取消对过滤器参数的引用，而不进行null检查和抛出 NullReferenceException` 当它缺席时。修补的工具：实践、提供者、服务地点、程序代码、交易、支付、收费、遭遇、患者（按id搜索+获取）、批量患者、预约。 如果没有0.2.5，每次GET调用都会因服务器端的NullRef而失败。
• 添加回归测试断言 `` 以WSDL要求的顺序发出（筛选前的字段）。

0.2.4 (2026-04-28)

• 修复（肥皂）: ` 子级现在按照WSDL要求的顺序进行序列化(CustomerKey → Password → User).上一个 CustomerKey → User → Password` 即使有有效的凭据，订单也会导致无声的授权失败。Tebra客服书面确认。

0.2.3 (2026-04-28)

• 修复（肥皂）: SOAPAction HTTP标头现在包括 KareoServices/ Kareo的调度程序所需的WCF合同段。已发送0.2.2及更早版本 ${SOAP_NAMESPACE}${operation}，调度器用HTTP 500拒绝了该请求(ContractFilter mismatch at the EndpointDispatcher).标头值现在也按照RFC 3902§3.2明确引用。
• 添加了一个回归测试，断言确切的标头值(npm test).

0.2.2 (2026-04-27)

• 修复（肥皂）: RequestHeader （User/Password/CustomerKey）现在被放置在Tebra的WSDL所期望的请求体中，而不是SOAP信封头中。

0.2.1 (2026-04-26)

• 发布到MCP注册表 com.jamesrosingmd/tebra （已验证的域命名空间）。

0.2.0

• 首次公开发布。

从0.2.4或更早版本紧急升级。 所有之前的版本都至少遇到了上述三线格式错误中的一个，只有0.2.5端到端满足Tebra的所有三个WSDL/运行时要求。

许可证

MIT许可证

版权所有（c）2026 James H.Rosing，医学博士，FACS

特此免费向任何获得副本的人授予许可 本软件和相关文档文件（“软件”），以处理 在软件中不受限制，包括但不限于权利 使用、复制、修改、合并、发布、分发、再许可和/或销售 软件的副本，并允许软件的接收者 根据以下条件提供：

上述版权声明和本许可声明应包含在所有 软件的副本或实质性部分。

软件按“原样”提供，不提供任何形式的明示或明示担保 隐含的，包括但不限于适销性保证， 适用于特定目的且不造成伤害。在任何情况下 作者或版权持有人对任何索赔、损害赔偿或其他 因以下原因产生的责任，无论是在合同、侵权或其他诉讼中， 出于或与软件、使用或其他交易有关 软件。