Doctor Appointment MCP Server

Un servidor Model Context Protocol (MCP) basado en Python para gestionar citas médicas a través de una API REST externa de citas.

El servidor expone operaciones de gestión de citas como herramientas MCP para que un agente o cliente de IA compatible con MCP pueda crear, buscar, recuperar, cancelar y reprogramar citas.

Qué hace

El servidor proporciona cinco herramientas MCP:

El servidor también incluye:

• Endpoint MCP Streamable HTTP en /mcp

• Endpoints de salud en / y /health

• Autenticación opcional mediante cabeceras HTTP personalizadas

• Un backend de API REST externo configurado mediante APPOINTMENTS_API

• Peticiones HTTP asíncronas con httpx

Related MCP server: MCP Appointment Booking Server

Arquitectura

AI Agent / MCP Client
          |
          | Model Context Protocol
          v
      /mcp endpoint
          |
          v
       Uvicorn
          |
          v
      Starlette
          |
          v
       FastMCP
          |
   +------+------+------+------+------+
   |      |      |      |      |
   v      v      v      v      v
 Create  Find   Check  Cancel Reschedule
   |      |      |      |      |
   +------+------+------+------+------+
                 |
                 v
            HTTPX Client
                 |
                 | REST API
                 v
        Appointment Backend
         (MockAPI by default)

Estructura del proyecto

doctor-appointment-mcp/
├── server.py
├── requirements.txt
├── start.sh
├── run.sh
├── README.md
├── .gitignore
└── .gitattributes

Requisitos

• Se recomienda Python 3.11 o superior

• pip

• Un endpoint de API REST de citas

Las dependencias de Python se definen en requirements.txt:

fastmcp>=3.0
uvicorn[standard]>=0.30
httpx>=0.27

Configuración local

1. Clonar el repositorio

git clone https://github.com/josh747jr/doctor-appointment-mcp.git
cd doctor-appointment-mcp

2. Crear un entorno virtual

Windows PowerShell:

python -m venv .venv
.\.venv\Scripts\Activate.ps1

Linux/macOS/WSL:

python3 -m venv .venv
source .venv/bin/activate

3. Instalar las dependencias

pip install -r requirements.txt

4. Configurar la API de citas

Establezca APPOINTMENTS_API en el endpoint REST que almacena los registros de citas.

Windows PowerShell:

$env:APPOINTMENTS_API="https://YOUR-API-ENDPOINT/appointments"

Linux/macOS/WSL:

export APPOINTMENTS_API="https://YOUR-API-ENDPOINT/appointments"

Si APPOINTMENTS_API no está definida, el server.py actual utiliza su endpoint MockAPI configurado.

No confirme claves de API, credenciales u otros secretos en el repositorio.

Ejecutar el servidor localmente

Inicie Uvicorn:

python -m uvicorn server:app --host 127.0.0.1 --port 8000

El endpoint MCP será:

http://127.0.0.1:8000/mcp

El endpoint de salud será:

http://127.0.0.1:8000/health

Una comprobación de salud correcta devuelve:

ok

Herramientas MCP

1. create_appointment

Crea una nueva cita médica.

Entradas:

• patient_name

• doctor_name

• appointment_date

• appointment_time

• reason — opcional

Ejemplo de argumentos de la herramienta:

{
  "patient_name": "John Doe",
  "doctor_name": "Dr. Mike",
  "appointment_date": "2026-09-18",
  "appointment_time": "2:00 PM",
  "reason": "Annual physical"
}

Las nuevas citas se almacenan con un estado de scheduled.

Ejemplo de solicitud de usuario:

Schedule an appointment for John Doe with Dr. Mike on September 18, 2026
at 2:00 PM for an annual physical.

2. find_appointments

Busca una o más citas existentes cuando no se conoce el ID de la cita.

Entradas de búsqueda:

• patient_name — opcional

• doctor_name — opcional

• appointment_date — opcional

• include_cancelled — booleano opcional, por defecto false

Debe proporcionarse al menos uno de los siguientes: patient_name, doctor_name o appointment_date.

Buscar citas de un paciente:

{
  "patient_name": "John Doe"
}

Buscar citas de un paciente y un médico:

{
  "patient_name": "John Doe",
  "doctor_name": "Dr. Mike"
}

Buscar citas en una fecha concreta:

{
  "appointment_date": "2026-09-18"
}

La herramienta envía los campos de búsqueda proporcionados como parámetros de consulta a la API REST de citas y devuelve los registros de citas coincidentes.

Un resultado correcto incluye:

{
  "success": true,
  "message": "Found 1 matching appointment(s).",
  "count": 1,
  "appointments": [
    {
      "id": "12",
      "patientName": "John Doe",
      "doctorName": "Dr. Mike",
      "appointmentDate": "2026-09-18",
      "appointmentTime": "2:00 PM",
      "reason": "Annual physical",
      "status": "scheduled"
    }
  ]
}

Si no hay registros coincidentes, la herramienta devuelve una respuesta correcta con count establecido en 0 y un array appointments vacío.

Ejemplos de solicitudes de usuario:

Find my appointment with Dr. Mike.

What appointments does John Doe have?

Find John Doe's appointment on September 18, 2026.

3. check_appointment_status

Recupera una cita por su ID.

Entrada:

• appointment_id

Ejemplo:

{
  "appointment_id": "12"
}

Una respuesta correcta incluye el paciente, el médico, la fecha de la cita, la hora de la cita, el motivo y el estado.

Ejemplo de solicitud de usuario:

What is the status of appointment 12?

4. cancel_appointment

Cancela una cita existente.

Entrada:

• appointment_id

Ejemplo:

{
  "appointment_id": "12"
}

La cancelación no elimina el registro de la cita. El servidor cambia su estado a:

cancelled

Conservar el registro preserva el historial de citas.

Ejemplo de solicitud de usuario:

Cancel appointment 12.

5. reschedule_appointment

Cambia la fecha y la hora de una cita existente.

Entradas:

• appointment_id

• new_appointment_date

• new_appointment_time

Ejemplo:

{
  "appointment_id": "12",
  "new_appointment_date": "2026-09-21",
  "new_appointment_time": "10:00 AM"
}

Las citas canceladas no pueden reprogramarse con la implementación actual.

Ejemplo de solicitud de usuario:

Move appointment 12 to September 21, 2026 at 10:00 AM.

Modelo de datos de citas

Se espera que el backend REST almacene registros similares a:

{
  "id": "12",
  "patientName": "John Doe",
  "doctorName": "Dr. Mike",
  "appointmentDate": "2026-09-18",
  "appointmentTime": "2:00 PM",
  "reason": "Annual physical",
  "status": "scheduled"
}

El servidor utiliza operaciones REST equivalentes a:

POST /appointments
GET  /appointments
GET  /appointments/{id}
PUT  /appointments/{id}

find_appointments utiliza GET /appointments con parámetros de consulta como:

patientName
doctorName
appointmentDate

Ejemplo de flujo de trabajo de agente

Un usuario puede preguntar primero:

Find my appointment with Dr. Mike.

El cliente MCP puede invocar:

find_appointments(patient_name="John Doe", doctor_name="Dr. Mike")

Después de encontrar el registro coincidente y el ID de la cita, el usuario puede decir:

Move that appointment to September 21 at 10 AM.

El cliente MCP puede entonces invocar:

reschedule_appointment(
    appointment_id="12",
    new_appointment_date="2026-09-21",
    new_appointment_time="10:00 AM"
)

Esto permite que un agente de IA localice primero una cita en lugar de exigir que el usuario conozca el ID de la cita.

Autenticación opcional mediante cabecera MCP

El servidor admite autenticación opcional mediante cabecera personalizada a través de la variable de entorno MCP_REQUEST_HEADERS.

Si la variable no está configurada, la autenticación mediante cabecera personalizada está desactivada.

Cabecera simple

Windows PowerShell:

$env:MCP_REQUEST_HEADERS="my-secret"

Linux/macOS/WSL:

export MCP_REQUEST_HEADERS="my-secret"

Esta configuración espera que las solicitudes MCP incluyan una cabecera denominada:

MCP_REQUEST_HEADERS

con el valor configurado.

Nombre de cabecera personalizado

La variable también puede contener JSON:

export MCP_REQUEST_HEADERS='{"X-API-Key":"my-secret"}'

El cliente MCP debe entonces enviar:

X-API-Key: my-secret

Los endpoints / y /health permanecen disponibles sin esta autenticación personalizada.

Nota de seguridad: Este proyecto es una implementación de demostración/aprendizaje. Una aplicación sanitaria real requiere una autenticación, autorización, controles de privacidad, registro de auditoría, gestión de secretos, protección de datos y revisión normativa sustancialmente más sólidos antes de almacenar información real de pacientes.

Despliegue

El repositorio contiene:

start.sh
run.sh

Estos scripts pueden utilizarse para un despliegue basado en Linux.

start.sh instala los paquetes de Python necesarios en el directorio de dependencias del despliegue.

run.sh inicia la aplicación con Uvicorn y escucha en la variable de entorno PORT, con el puerto 8080 como valor predeterminado.

Variable de entorno de despliegue necesaria:

APPOINTMENTS_API=https://YOUR-API-ENDPOINT/appointments

Autenticación opcional:

MCP_REQUEST_HEADERS=your-secret

Después del despliegue, el endpoint MCP normalmente será:

https://YOUR-SERVER/mcp

y el endpoint de salud:

https://YOUR-SERVER/health

Pruebas del servidor

Inicie la aplicación:

python -m uvicorn server:app --host 127.0.0.1 --port 8000

Pruebe el endpoint de salud:

curl http://127.0.0.1:8000/health

Respuesta esperada:

ok

A continuación, configure un cliente compatible con MCP para conectarse a:

http://127.0.0.1:8000/mcp

El cliente debería descubrir estas cinco herramientas:

create_appointment
find_appointments
check_appointment_status
cancel_appointment
reschedule_appointment

Mejoras previstas

Los siguientes pasos útiles incluyen:

• Añadir consulta de disponibilidad y franjas horarias de médicos

• Evitar citas conflictivas o duplicadas

• Añadir una validación más sólida de fecha y hora

• Añadir una base de datos de producción

• Añadir OAuth u otro mecanismo de autenticación de nivel de producción

• Añadir pruebas automatizadas

• Añadir registro de auditoría estructurado

• Integrar con un calendario real o un proveedor de programación

• Añadir controles de identidad y autorización de pacientes de nivel de producción

Estado de desarrollo

Este proyecto está pensado como un proyecto de desarrollo y aprendizaje de MCP. El backend de citas actual puede sustituirse posteriormente por un servicio de programación o una base de datos de producción conservando la interfaz de herramientas orientada a MCP.

Seguridad y datos sanitarios

No utilice información real de pacientes ni información sanitaria protegida (PHI) con un backend de demostración no seguro.

Una aplicación sanitaria de producción puede estar sujeta a requisitos de privacidad, seguridad, cumplimiento normativo y retención de datos, como HIPAA en Estados Unidos.

Repositorio

https://github.com/josh747jr/doctor-appointment-mcp

Licencia

Todavía no se ha especificado ninguna licencia para este repositorio. Añada un archivo LICENSE antes de distribuir o reutilizar el proyecto bajo términos de licencia específicos.