Skip to main content
Glama
mcp-cliniko

mcp-cliniko

MCP Cliniko Server

A Model Context Protocol (MCP) server that provides integration with the Cliniko API for healthcare practice management.

Features

Tools (Actions)

  • Patient Management

    • list_patients - Search and list patients

    • get_patient - Get patient by ID

    • create_patient - Create new patient

    • update_patient - Update patient details

    • delete_patient - Archive patient

  • Appointment Management

    • list_appointments - Search and list appointments

    • get_appointment - Get appointment by ID

    • create_appointment - Book new appointment

    • update_appointment - Modify appointment

    • cancel_appointment - Cancel appointment

    • delete_appointment - Delete appointment

    • get_available_times - Get practitioner availability

  • Invoice Management

    • list_invoices - List and filter invoices

    • get_invoice - Get invoice details

    • create_invoice - Create new invoice

    • update_invoice - Update invoice status or details

    • delete_invoice - Delete draft invoice

  • Invoice Items

    • list_invoice_items - List items on an invoice

    • add_invoice_item - Add item to invoice

    • update_invoice_item - Modify invoice item

    • delete_invoice_item - Remove item from invoice

  • Payment Processing

    • list_payments - List payments with filtering

    • create_payment - Record a payment

    • delete_payment - Delete payment record

  • Products & Services

    • list_products - List billable products/services

    • get_product - Get product details

    • create_product - Create new product/service

  • Tax Configuration

    • list_taxes - List available tax rates

    • get_tax - Get tax details

  • Complex Workflows

    • create_invoice_from_appointments - Generate invoices from appointments

    • bulk_invoice_generation - Bulk create invoices for date range

    • list_patient_cases - List patient cases

    • list_invoices_for_case - Get invoices for a case

  • Supporting Tools

    • list_practitioners - List all practitioners

    • list_appointment_types - List appointment types

    • list_businesses - List businesses

  • Test Data

    • generate_test_data - Generate synthetic Australian healthcare data

    • cleanup_test_data - Remove test patients

Resources (Data Access)

  • patient://{id} - Individual patient data

  • patients://list - All patients

  • appointment://{id} - Individual appointment

  • appointments://list - All appointments

  • appointments://today - Today's appointments

  • practitioners://list - All practitioners

  • businesses://list - All businesses

  • appointment-types://list - All appointment types

  • openapi://spec - Cliniko API OpenAPI specification (YAML format)

Related MCP server: Cliniko MCP Server

Installation

  1. Clone the repository:

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

npm install
  1. Set up your Cliniko API key:

cp .env.example .env
# Edit .env and add your Cliniko API key
  1. Build the project:

npm run build

Configuration

Environment Variables

  • CLINIKO_API_KEY - Your Cliniko API key (required)

Getting a Cliniko API Key

  1. Log into your Cliniko account

  2. Go to Settings → Integrations → API Keys

  3. Create a new API key

  4. Copy the key to your .env file

Usage

Development Mode

npm run dev

Production Mode

npm start

Testing with MCP Inspector

npm run inspect

Integration with Claude Desktop

Add to your Claude Desktop configuration (~/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"
      }
    }
  }
}

Examples

Using Tools

List Patients:

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

Create Patient:

{
  "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"
  }
}

Book Appointment:

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

Generate Test Data:

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

Using Resources

Resources provide read-only access to Cliniko data:

  • patient://123 - Get patient with ID 123

  • patients://list - List all patients

  • appointments://today - Get today's appointments

API Rate Limits

Cliniko API has a rate limit of 200 requests per minute. The server does not implement rate limiting internally, so be mindful of this limit when making bulk operations.

Error Handling

The server uses standard HTTP error conventions:

  • 400 - Bad Request

  • 401 - Unauthorized (check API key)

  • 404 - Resource not found

  • 429 - Rate limit exceeded

  • 500 - Internal server error

Development

Project Structure

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

Building

npm run build

Type Checking

npx tsc --noEmit

License

MIT

Support

For Cliniko API documentation, visit: https://docs.api.cliniko.com/

For MCP documentation, visit: https://modelcontextprotocol.io/# mcp-cliniko

Available Tools

27 tools
cancel_appointmentC

Cancel an appointment

Inputs: appointment_id (required), cancellation_reason.

cleanup_comprehensive_test_dataC

Clean up all test data with granular control and dry-run option

Inputs: delete_patients, delete_appointments, delete_invoices, delete_products, +3 more.

cleanup_test_dataA

Delete all test patients (patients with emails ending in @gmail.com, @outlook.com, etc)

Inputs: no named parameters.

create_appointmentC

Create a new appointment

Inputs: starts_at (required), practitioner_id (required), appointment_type_id (required), business_id (required), +2 more.

create_patientC

Create a new patient

Inputs: first_name (required), last_name (required), title, preferred_name, +12 more.

delete_appointmentC

Delete an appointment completely

Inputs: appointment_id (required).

delete_patientA

Delete (archive) a patient

Inputs: patient_id (required).

demo_invoice_generationA

Demo: Generate test patients and appointments, then show how to create invoices. NOTE: Cliniko API is READ-ONLY for invoices - they must be created via the web interface.

Inputs: target_date, num_patients, num_appointments, clear_existing, +1 more.

display_invoices_for_dateB

Display all existing invoices for a specific date (READ-ONLY). Invoices must be created manually in Cliniko.

Inputs: target_date (required), display_format.

generate_comprehensive_test_dataB

Generate comprehensive synthetic test data across all Cliniko categories

Inputs: num_patients, num_contacts, num_relationships, num_appointments, +11 more.

generate_test_dataB

Generate synthetic test data for Cliniko (Australian healthcare data)

Inputs: num_patients, num_appointments, days_ahead.

get_appointmentC

Get a specific appointment by ID

Inputs: appointment_id (required).

get_appointment_invoicesA

Get invoices for a specific appointment (READ-ONLY)

Inputs: appointment_id (required).

get_available_timesC

Get available appointment times for a practitioner

Inputs: business_id (required), practitioner_id (required), from (required), to (required).

get_invoiceA

Get details of a specific invoice (READ-ONLY)

Inputs: invoice_id (required).

get_patientC

Get a specific patient by ID

Inputs: patient_id (required).

get_patient_invoicesA

Get invoices for a specific patient (READ-ONLY)

Inputs: patient_id (required).

how_to_create_invoicesB

Get instructions on how to create invoices in Cliniko (manual process)

Inputs: no named parameters.

list_appointmentsC

List or search for appointments

Inputs: patient_id, practitioner_id, business_id, starts_at, +4 more.

list_appointment_typesB

List all appointment types

Inputs: page, per_page.

list_businessesB

List all businesses

Inputs: no named parameters.

list_invoice_itemsB

List items in an invoice (READ-ONLY)

Inputs: invoice_id (required).

list_invoicesB

List invoices with filtering options (READ-ONLY - invoices must be created in Cliniko web interface)

Inputs: page, per_page, patient_id, practitioner_id, +3 more.

list_patientsC

List or search for patients

Inputs: q, page, per_page.

list_practitionersC

List all practitioners

Inputs: page, per_page.

update_appointmentC

Update an existing appointment

Inputs: appointment_id (required), starts_at, notes, patient_id.

update_patientC

Update an existing patient

Inputs: patient_id (required), first_name, last_name, title, +13 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.2/5.0

    Scored across 27 tools

    Disambiguation4/5

    Most tools target distinct resources (patients, appointments, invoices) with clear purposes. However, cleanup_test_data and cleanup_comprehensive_test_data are very similar, and demo_invoice_generation overlaps with how_to_create_invoices in providing guidance.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern in snake_case (e.g., create_patient, list_appointments, delete_patient). No mixing of styles or ambiguous verbs.

    Tool Count3/5

    27 tools is slightly high for a healthcare practice server. Multiple test data generation and cleanup tools add redundancy, and several invoice tools are read-only due to API limitations, reducing effective utility. A more streamlined set (around 15-20) would be better.

    Completeness4/5

    CRUD operations are covered for patients and appointments, along with listings and searches. Invoice operations are read-only but acknowledged. Missing features like appointment notes or patient tags are minor given the domain focus.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables interaction with Athena Health's API for comprehensive healthcare practice management. Supports appointment scheduling, provider and department management, patient search, and available slot discovery through natural language.
      -
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables integration with the Cliniko practice management system through MCP tools and resources. Supports patient management, appointment scheduling, and practice data access through natural language interactions.
      -
    • F
      license
      Not graded
      quality
      C
      maintenance
      Exposes tools from the Ecuro Light API for managing clinical appointments, patient records, and clinic availability. It enables users to perform healthcare management tasks such as scheduling, patient search, and report generation through MCP-compatible clients.
      -
    • A
      license
      B
      quality
      D
      maintenance
      Provides comprehensive integration with the Cliniko API for healthcare practice management, including patient, appointment, and invoice administration. It enables tools for complex clinical workflows and direct access to practice resources through the Model Context Protocol.
      27
      2
      MIT