Doctor Appointment MCP Server

Ein Python-basierter Model Context Protocol (MCP)-Server zur Verwaltung von Arztterminen über eine externe Termin-REST-API.

Der Server stellt Terminverwaltungsoperationen als MCP-Tools bereit, sodass ein MCP-kompatibler KI-Agent oder Client Termine erstellen, finden, abrufen, stornieren und verschieben kann.

Was es tut

Der Server stellt fünf MCP-Tools bereit:

Der Server enthält außerdem:

• Streambarer HTTP-MCP-Endpunkt unter /mcp

• Health-Endpunkte unter / und /health

• Optionale Authentifizierung über benutzerdefinierte HTTP-Header

• Ein externes REST-API-Backend, das über APPOINTMENTS_API konfiguriert wird

• Asynchrone HTTP-Anfragen mit httpx

Related MCP server: MCP Appointment Booking Server

Architektur

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)

Projektstruktur

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

Anforderungen

• Python 3.11 oder neuer empfohlen

• pip

• Einen REST-API-Endpunkt für Termine

Python-Abhängigkeiten sind in requirements.txt definiert:

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

Lokale Einrichtung

1. Repository klonen

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

2. Virtuelle Umgebung erstellen

Windows PowerShell:

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

Linux/macOS/WSL:

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

3. Abhängigkeiten installieren

pip install -r requirements.txt

4. Termin-API konfigurieren

Setzen Sie APPOINTMENTS_API auf den REST-Endpunkt, der Termindatensätze speichert.

Windows PowerShell:

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

Linux/macOS/WSL:

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

Wenn APPOINTMENTS_API nicht gesetzt ist, verwendet das aktuelle server.py seinen konfigurierten MockAPI-Endpunkt.

Committen Sie keine API-Schlüssel, Anmeldedaten oder andere Geheimnisse in das Repository.

Server lokal ausführen

Starten Sie Uvicorn:

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

Der MCP-Endpunkt wird sein:

http://127.0.0.1:8000/mcp

Der Health-Endpunkt wird sein:

http://127.0.0.1:8000/health

Ein erfolgreicher Health-Check gibt zurück:

ok

MCP-Tools

1. create_appointment

Erstellt einen neuen Arzttermin.

Eingaben:

• patient_name

• doctor_name

• appointment_date

• appointment_time

• reason — optional

Beispiel-Tool-Argumente:

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

Neue Termine werden mit dem Status scheduled gespeichert.

Beispiel-Benutzeranfrage:

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

2. find_appointments

Findet einen oder mehrere bestehende Termine, wenn die Termin-ID nicht bekannt ist.

Sucheingaben:

• patient_name — optional

• doctor_name — optional

• appointment_date — optional

• include_cancelled — optionaler boolescher Wert, Standard ist false

Mindestens eines von patient_name, doctor_name oder appointment_date muss angegeben werden.

Termine für einen Patienten finden:

{
  "patient_name": "John Doe"
}

Termine für einen Patienten und einen Arzt finden:

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

Termine an einem bestimmten Datum finden:

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

Das Tool sendet die angegebenen Suchfelder als Abfrageparameter an die Termin-REST-API und gibt die passenden Termindatensätze zurück.

Ein erfolgreiches Ergebnis enthält:

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

Wenn keine Datensätze übereinstimmen, gibt das Tool eine erfolgreiche Antwort mit count auf 0 und einem leeren appointments-Array zurück.

Beispiel-Benutzeranfragen:

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

Ruft einen Termin anhand seiner ID ab.

Eingabe:

• appointment_id

Beispiel:

{
  "appointment_id": "12"
}

Eine erfolgreiche Antwort enthält den Patienten, den Arzt, das Termindatum, die Terminuhrzeit, den Grund und den Status.

Beispiel-Benutzeranfrage:

What is the status of appointment 12?

4. cancel_appointment

Storniert einen bestehenden Termin.

Eingabe:

• appointment_id

Beispiel:

{
  "appointment_id": "12"
}

Die Stornierung löscht den Termindatensatz nicht. Der Server ändert seinen Status auf:

cancelled

Das Aufbewahren des Datensatzes erhält die Terminhistorie.

Beispiel-Benutzeranfrage:

Cancel appointment 12.

5. reschedule_appointment

Ändert Datum und Uhrzeit eines bestehenden Termins.

Eingaben:

• appointment_id

• new_appointment_date

• new_appointment_time

Beispiel:

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

Stornierte Termine können von der aktuellen Implementierung nicht verschoben werden.

Beispiel-Benutzeranfrage:

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

Termin-Datenmodell

Das REST-Backend soll Datensätze ähnlich wie folgt speichern:

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

Der Server verwendet REST-Operationen, die Folgendem entsprechen:

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

find_appointments verwendet GET /appointments mit Abfrageparametern wie:

patientName
doctorName
appointmentDate

Beispiel-Agenten-Workflow

Ein Benutzer könnte zuerst fragen:

Find my appointment with Dr. Mike.

Der MCP-Client kann aufrufen:

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

Nachdem der passende Datensatz und die Termin-ID gefunden wurden, kann der Benutzer sagen:

Move that appointment to September 21 at 10 AM.

Der MCP-Client kann dann aufrufen:

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

Dies ermöglicht einem KI-Agenten, zuerst einen Termin zu finden, anstatt dass der Benutzer die Termin-ID kennen muss.

Optionale MCP-Header-Authentifizierung

Der Server unterstützt optionale Authentifizierung über benutzerdefinierte Header durch die Umgebungsvariable MCP_REQUEST_HEADERS.

Wenn die Variable nicht konfiguriert ist, ist die Authentifizierung über benutzerdefinierte Header deaktiviert.

Einfacher Header

Windows PowerShell:

$env:MCP_REQUEST_HEADERS="my-secret"

Linux/macOS/WSL:

export MCP_REQUEST_HEADERS="my-secret"

Diese Konfiguration erwartet, dass MCP-Anfragen einen Header mit dem Namen enthalten:

MCP_REQUEST_HEADERS

mit dem konfigurierten Wert.

Benutzerdefinierter Headername

Die Variable kann auch JSON enthalten:

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

Der MCP-Client muss dann senden:

X-API-Key: my-secret

Die Endpunkte / und /health bleiben ohne diese benutzerdefinierte Authentifizierung verfügbar.

Sicherheitshinweis: Dieses Projekt ist eine Demonstrations-/Lernimplementierung. Eine echte Gesundheitsanwendung erfordert wesentlich stärkere Authentifizierung, Autorisierung, Datenschutzkontrollen, Audit-Protokollierung, Geheimnisverwaltung, Datenschutz und behördliche Überprüfung, bevor echte Patientendaten gespeichert werden.

Bereitstellung

Das Repository enthält:

start.sh
run.sh

Diese Skripte können für eine Linux-basierte Bereitstellung verwendet werden.

start.sh installiert die erforderlichen Python-Pakete in das Bereitstellungs-Abhängigkeitsverzeichnis.

run.sh startet die Anwendung mit Uvicorn und lauscht auf der Umgebungsvariable PORT, standardmäßig auf Port 8080.

Erforderliche Umgebungsvariable für die Bereitstellung:

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

Optionale Authentifizierung:

MCP_REQUEST_HEADERS=your-secret

Nach der Bereitstellung ist der MCP-Endpunkt normalerweise:

https://YOUR-SERVER/mcp

und der Health-Endpunkt:

https://YOUR-SERVER/health

Testen des Servers

Starten Sie die Anwendung:

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

Testen Sie den Health-Endpunkt:

curl http://127.0.0.1:8000/health

Erwartete Antwort:

ok

Konfigurieren Sie dann einen MCP-kompatiblen Client, um sich zu verbinden mit:

http://127.0.0.1:8000/mcp

Der Client sollte diese fünf Tools erkennen:

create_appointment
find_appointments
check_appointment_status
cancel_appointment
reschedule_appointment

Geplante Verbesserungen

Nützliche nächste Schritte sind:

• Verfügbarkeit von Ärzten und Zeitslot-Suche hinzufügen

• Konflikte oder Doppelbuchungen von Terminen verhindern

• Stärkere Datums- und Zeitvalidierung hinzufügen

• Eine Produktionsdatenbank hinzufügen

• OAuth oder einen anderen produktionsreifen Authentifizierungsmechanismus hinzufügen

• Automatisierte Tests hinzufügen

• Strukturierte Audit-Protokollierung hinzufügen

• Integration mit einem echten Kalender- oder Planungsanbieter

• Produktionsreife Patientenidentitäts- und Autorisierungskontrollen hinzufügen

Entwicklungsstatus

Dieses Projekt ist als MCP-Entwicklungs- und Lernprojekt gedacht. Das aktuelle Termin-Backend kann später durch einen Produktionsplanungsdienst oder eine Datenbank ersetzt werden, während die MCP-orientierte Tool-Schnittstelle erhalten bleibt.

Sicherheit und Gesundheitsdaten

Verwenden Sie keine echten Patientendaten oder geschützten Gesundheitsinformationen (PHI) mit einem ungesicherten Demonstrations-Backend.

Eine Produktions-Gesundheitsanwendung kann Datenschutz-, Sicherheits-, Compliance- und Datenaufbewahrungsanforderungen wie HIPAA in den Vereinigten Staaten unterliegen.

Repository

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

Lizenz

Für dieses Repository wurde noch keine Lizenz festgelegt. Fügen Sie eine LICENSE-Datei hinzu, bevor Sie das Projekt unter bestimmten Lizenzbedingungen verteilen oder wiederverwenden.