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)

Installation

1. Clone the repository:

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

2. Install dependencies:

npm install

3. Set up your Cliniko API key:

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

4. 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