MCP Cliniko 服务器

一个模型上下文协议 (MCP) 服务器，提供与 Cliniko API 的集成，用于医疗实践管理。

功能

工具 (操作)

患者管理
- list_patients - 搜索并列出患者
- get_patient - 通过 ID 获取患者
- create_patient - 创建新患者
- update_patient - 更新患者详细信息
- delete_patient - 归档患者
预约管理
- list_appointments - 搜索并列出预约
- get_appointment - 通过 ID 获取预约
- create_appointment - 预订新预约
- update_appointment - 修改预约
- cancel_appointment - 取消预约
- delete_appointment - 删除预约
- get_available_times - 获取从业者空闲时间
发票管理
- list_invoices - 列出并筛选发票
- get_invoice - 获取发票详细信息
- create_invoice - 创建新发票
- update_invoice - 更新发票状态或详细信息
- delete_invoice - 删除草稿发票
发票项目
- list_invoice_items - 列出发票上的项目
- add_invoice_item - 向发票添加项目
- update_invoice_item - 修改发票项目
- delete_invoice_item - 从发票中移除项目
支付处理
- list_payments - 筛选并列出支付记录
- create_payment - 记录支付
- delete_payment - 删除支付记录
产品与服务
- list_products - 列出可计费产品/服务
- get_product - 获取产品详细信息
- create_product - 创建新产品/服务
税务配置
- list_taxes - 列出可用税率
- get_tax - 获取税务详细信息
复杂工作流
- create_invoice_from_appointments - 从预约生成发票
- bulk_invoice_generation - 批量创建日期范围内的发票
- list_patient_cases - 列出患者病例
- list_invoices_for_case - 获取病例的发票
辅助工具
- list_practitioners - 列出所有从业者
- list_appointment_types - 列出预约类型
- list_businesses - 列出企业
测试数据
- generate_test_data - 生成合成的澳大利亚医疗数据
- cleanup_test_data - 移除测试患者

资源 (数据访问)

patient://{id} - 单个患者数据
patients://list - 所有患者
appointment://{id} - 单个预约
appointments://list - 所有预约
appointments://today - 今日预约
practitioners://list - 所有从业者
businesses://list - 所有企业
appointment-types://list - 所有预约类型
openapi://spec - Cliniko API OpenAPI 规范 (YAML 格式)

安装

克隆仓库：

git clone https://github.com/yourusername/mcp-cliniko.git
cd mcp-cliniko

安装依赖：

npm install

设置您的 Cliniko API 密钥：

cp .env.example .env
# Edit .env and add your Cliniko API key

构建项目：

npm run build

配置

环境变量

CLINIKO_API_KEY - 您的 Cliniko API 密钥 (必需)

获取 Cliniko API 密钥

登录您的 Cliniko 账户
前往设置 → 集成 → API 密钥
创建一个新的 API 密钥
将密钥复制到您的 .env 文件中

使用方法

开发模式

npm run dev

生产模式

npm start

使用 MCP Inspector 进行测试

npm run inspect

与 Claude Desktop 集成

添加到您的 Claude Desktop 配置 (~/Library/Application Support/Claude/claude_desktop_config.json)：

{
  "mcpServers": {
    "cliniko": {
      "command": "node",
      "args": ["/path/to/mcp-cliniko/dist/index.js"],
      "env": {
        "CLINIKO_API_KEY": "your-api-key-here"
      }
    }
  }
}

示例

使用工具

列出患者：

{
  "tool": "list_patients",
  "arguments": {
    "q": "Smith",
    "per_page": 10
  }
}

创建患者：

{
  "tool": "create_patient",
  "arguments": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com",
    "phone_number": "0412345678",
    "date_of_birth": "1980-01-15",
    "medicare_number": "1234567890"
  }
}

预订预约：

{
  "tool": "create_appointment",
  "arguments": {
    "starts_at": "2024-01-20T10:00:00Z",
    "patient_id": 123,
    "practitioner_id": 456,
    "appointment_type_id": 789,
    "business_id": 101
  }
}

生成测试数据：

{
  "tool": "generate_test_data",
  "arguments": {
    "num_patients": 5,
    "num_appointments": 10,
    "days_ahead": 7
  }
}

使用资源

资源提供对 Cliniko 数据的只读访问：

patient://123 - 获取 ID 为 123 的患者
patients://list - 列出所有患者
appointments://today - 获取今日预约

API 速率限制

Cliniko API 的速率限制为每分钟 200 次请求。服务器内部未实现速率限制，因此在进行批量操作时请注意此限制。

错误处理

服务器使用标准的 HTTP 错误约定：

400 - 错误请求
401 - 未授权 (检查 API 密钥)
404 - 未找到资源
429 - 超出速率限制
500 - 内部服务器错误

开发

项目结构

mcp-cliniko/
├── src/
│   ├── index.ts              # Main server
│   ├── cliniko-client.ts     # API client
│   ├── types.ts              # TypeScript types
│   ├── tools/                # MCP tools
│   │   ├── patients.ts
│   │   ├── appointments.ts
│   │   └── synthetic-data.ts
│   └── resources/            # MCP resources
│       └── index.ts
├── dist/                     # Compiled JavaScript
├── package.json
├── tsconfig.json
└── .env

构建

npm run build

类型检查

npx tsc --noEmit

许可证

MIT

支持

有关 Cliniko API 文档，请访问：https://docs.api.cliniko.com/

有关 MCP 文档，请访问：https://modelcontextprotocol.io/

mcp-cliniko