MCP Cliniko サーバー

医療機関向け管理システム「Cliniko」のAPIと連携するためのModel Context Protocol (MCP) サーバーです。

機能

ツール (アクション)

患者管理
- 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アカウントにログイン
「Settings」→「Integrations」→「API Keys」へ移動
新しい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のレート制限は1分間に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