mcp-cliniko
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-cliniko show me today's appointments"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 patientsget_patient- Get patient by IDcreate_patient- Create new patientupdate_patient- Update patient detailsdelete_patient- Archive patient
Appointment Management
list_appointments- Search and list appointmentsget_appointment- Get appointment by IDcreate_appointment- Book new appointmentupdate_appointment- Modify appointmentcancel_appointment- Cancel appointmentdelete_appointment- Delete appointmentget_available_times- Get practitioner availability
Invoice Management
list_invoices- List and filter invoicesget_invoice- Get invoice detailscreate_invoice- Create new invoiceupdate_invoice- Update invoice status or detailsdelete_invoice- Delete draft invoice
Invoice Items
list_invoice_items- List items on an invoiceadd_invoice_item- Add item to invoiceupdate_invoice_item- Modify invoice itemdelete_invoice_item- Remove item from invoice
Payment Processing
list_payments- List payments with filteringcreate_payment- Record a paymentdelete_payment- Delete payment record
Products & Services
list_products- List billable products/servicesget_product- Get product detailscreate_product- Create new product/service
Tax Configuration
list_taxes- List available tax ratesget_tax- Get tax details
Complex Workflows
create_invoice_from_appointments- Generate invoices from appointmentsbulk_invoice_generation- Bulk create invoices for date rangelist_patient_cases- List patient caseslist_invoices_for_case- Get invoices for a case
Supporting Tools
list_practitioners- List all practitionerslist_appointment_types- List appointment typeslist_businesses- List businesses
Test Data
generate_test_data- Generate synthetic Australian healthcare datacleanup_test_data- Remove test patients
Resources (Data Access)
patient://{id}- Individual patient datapatients://list- All patientsappointment://{id}- Individual appointmentappointments://list- All appointmentsappointments://today- Today's appointmentspractitioners://list- All practitionersbusinesses://list- All businessesappointment-types://list- All appointment typesopenapi://spec- Cliniko API OpenAPI specification (YAML format)
Related MCP server: Cliniko MCP Server
Installation
Clone the repository:
git clone https://github.com/yourusername/mcp-cliniko.git
cd mcp-clinikoInstall dependencies:
npm installSet up your Cliniko API key:
cp .env.example .env
# Edit .env and add your Cliniko API keyBuild the project:
npm run buildConfiguration
Environment Variables
CLINIKO_API_KEY- Your Cliniko API key (required)
Getting a Cliniko API Key
Log into your Cliniko account
Go to Settings → Integrations → API Keys
Create a new API key
Copy the key to your
.envfile
Usage
Development Mode
npm run devProduction Mode
npm startTesting with MCP Inspector
npm run inspectIntegration 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 123patients://list- List all patientsappointments://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
└── .envBuilding
npm run buildType Checking
npx tsc --noEmitLicense
MIT
Support
For Cliniko API documentation, visit: https://docs.api.cliniko.com/
For MCP documentation, visit: https://modelcontextprotocol.io/# mcp-cliniko
Available Tools
27 toolscancel_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
Scored across 27 tools
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.
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.
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.
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
Related MCP Connectors
Read splose patients, appointments, invoices, cases; book and cancel appointments, record payments.
Hosted MCP server for Cliniko — patients, appointments, availability, and invoices for AI agents.
Read Halaxy patients, appointments, slots and invoices; create patients, appointments and notes.
Search clients, appointments, intakes, notes and invoices in IntakeQ, and book or cancel visits.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables 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.-
- FlicenseNot gradedqualityDmaintenanceEnables 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.-
- FlicenseNot gradedqualityCmaintenanceExposes 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.-
- AlicenseBqualityDmaintenanceProvides 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.272MIT