MCP Cliniko 서버

의료 진료 관리를 위한 Cliniko API와의 통합을 제공하는 MCP(Model Context Protocol) 서버입니다.

기능

도구 (작업)

환자 관리
- 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 키(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는 분당 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