Servidor MCP Cliniko

Un servidor del Protocolo de Contexto de Modelos (MCP) que proporciona integración con la API de Cliniko para la gestión de consultas sanitarias.

Características

Herramientas (Acciones)

Gestión de pacientes
- list_patients - Buscar y listar pacientes
- get_patient - Obtener paciente por ID
- create_patient - Crear nuevo paciente
- update_patient - Actualizar detalles del paciente
- delete_patient - Archivar paciente
Gestión de citas
- list_appointments - Buscar y listar citas
- get_appointment - Obtener cita por ID
- create_appointment - Reservar nueva cita
- update_appointment - Modificar cita
- cancel_appointment - Cancelar cita
- delete_appointment - Eliminar cita
- get_available_times - Obtener disponibilidad del profesional
Gestión de facturas
- list_invoices - Listar y filtrar facturas
- get_invoice - Obtener detalles de la factura
- create_invoice - Crear nueva factura
- update_invoice - Actualizar estado o detalles de la factura
- delete_invoice - Eliminar factura en borrador
Artículos de factura
- list_invoice_items - Listar artículos de una factura
- add_invoice_item - Añadir artículo a la factura
- update_invoice_item - Modificar artículo de la factura
- delete_invoice_item - Eliminar artículo de la factura
Procesamiento de pagos
- list_payments - Listar pagos con filtros
- create_payment - Registrar un pago
- delete_payment - Eliminar registro de pago
Productos y servicios
- list_products - Listar productos/servicios facturables
- get_product - Obtener detalles del producto
- create_product - Crear nuevo producto/servicio
Configuración de impuestos
- list_taxes - Listar tipos impositivos disponibles
- get_tax - Obtener detalles del impuesto
Flujos de trabajo complejos
- create_invoice_from_appointments - Generar facturas a partir de citas
- bulk_invoice_generation - Crear facturas en lote para un rango de fechas
- list_patient_cases - Listar casos de pacientes
- list_invoices_for_case - Obtener facturas para un caso
Herramientas de soporte
- list_practitioners - Listar todos los profesionales
- list_appointment_types - Listar tipos de cita
- list_businesses - Listar empresas
Datos de prueba
- generate_test_data - Generar datos sanitarios sintéticos de Australia
- cleanup_test_data - Eliminar pacientes de prueba

Recursos (Acceso a datos)

patient://{id} - Datos individuales del paciente
patients://list - Todos los pacientes
appointment://{id} - Cita individual
appointments://list - Todas las citas
appointments://today - Citas de hoy
practitioners://list - Todos los profesionales
businesses://list - Todas las empresas
appointment-types://list - Todos los tipos de cita
openapi://spec - Especificación OpenAPI de la API de Cliniko (formato YAML)

Instalación

Clonar el repositorio:

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

Instalar dependencias:

npm install

Configurar tu clave de API de Cliniko:

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

Construir el proyecto:

npm run build

Configuración

Variables de entorno

CLINIKO_API_KEY - Tu clave de API de Cliniko (obligatorio)

Obtener una clave de API de Cliniko

Inicia sesión en tu cuenta de Cliniko
Ve a Ajustes → Integraciones → Claves de API
Crea una nueva clave de API
Copia la clave en tu archivo .env

Uso

Modo desarrollo

npm run dev

Modo producción

npm start

Pruebas con MCP Inspector

npm run inspect

Integración con Claude Desktop

Añadir a tu configuración de 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"
      }
    }
  }
}

Ejemplos

Uso de herramientas

Listar pacientes:

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

Crear paciente:

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

Reservar cita:

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

Generar datos de prueba:

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

Uso de recursos

Los recursos proporcionan acceso de solo lectura a los datos de Cliniko:

patient://123 - Obtener paciente con ID 123
patients://list - Listar todos los pacientes
appointments://today - Obtener las citas de hoy

Límites de tasa de la API

La API de Cliniko tiene un límite de 200 solicitudes por minuto. El servidor no implementa limitación de tasa internamente, así que ten en cuenta este límite al realizar operaciones masivas.

Gestión de errores

El servidor utiliza las convenciones de error HTTP estándar:

400 - Solicitud incorrecta
401 - No autorizado (comprueba la clave de API)
404 - Recurso no encontrado
429 - Límite de tasa excedido
500 - Error interno del servidor

Desarrollo

Estructura del proyecto

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

Construcción

npm run build

Comprobación de tipos

npx tsc --noEmit

Licencia

MIT

Soporte

Para la documentación de la API de Cliniko, visita: https://docs.api.cliniko.com/

Para la documentación de MCP, visita: https://modelcontextprotocol.io/

mcp-cliniko