Doctor Appointment MCP Server

A Python-based Model Context Protocol (MCP) server for managing doctor appointments through an external appointment REST API.

The server exposes appointment-management operations as MCP tools so an MCP-compatible AI agent or client can create, find, retrieve, cancel, and reschedule appointments.

What It Does

The server provides five MCP tools:

Tool	Description
create_appointment	Creates a new doctor appointment.
find_appointments	Finds appointments by patient name, doctor name, and/or appointment date.
check_appointment_status	Retrieves appointment details and status by appointment ID.
cancel_appointment	Cancels an appointment by changing its status to cancelled.
reschedule_appointment	Changes the date and time of an existing appointment.

The server also includes:

• Streamable HTTP MCP endpoint at /mcp
• Health endpoints at / and /health
• Optional custom HTTP-header authentication
• An external REST API backend configured through APPOINTMENTS_API
• Async HTTP requests using httpx

Architecture

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)

Project Structure

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

Requirements

• Python 3.11 or newer recommended
• pip
• An appointment REST API endpoint

Python dependencies are defined in requirements.txt:

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

Local Setup

1. Clone the repository

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

2. Create a virtual environment

Windows PowerShell:

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

Linux/macOS/WSL:

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

3. Install dependencies

pip install -r requirements.txt

4. Configure the appointment API

Set APPOINTMENTS_API to the REST endpoint that stores appointment records.

Windows PowerShell:

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

Linux/macOS/WSL:

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

If APPOINTMENTS_API is not set, the current server.py uses its configured MockAPI endpoint.

Do not commit API keys, credentials, or other secrets to the repository.

Run the Server Locally

Start Uvicorn:

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

The MCP endpoint will be:

http://127.0.0.1:8000/mcp

The health endpoint will be:

http://127.0.0.1:8000/health

A successful health check returns:

ok

MCP Tools

1. create_appointment

Creates a new doctor appointment.

Inputs:

• patient_name
• doctor_name
• appointment_date
• appointment_time
• reason — optional

Example tool arguments:

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

New appointments are stored with a status of scheduled.

Example user request:

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

2. find_appointments

Finds one or more existing appointments when the appointment ID is not known.

Search inputs:

• patient_name — optional
• doctor_name — optional
• appointment_date — optional
• include_cancelled — optional boolean, defaults to false

At least one of patient_name, doctor_name, or appointment_date must be provided.

Find appointments for a patient:

{
  "patient_name": "John Doe"
}

Find appointments for a patient and doctor:

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

Find appointments on a particular date:

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

The tool sends the supplied search fields as query parameters to the appointment REST API and returns the matching appointment records.

A successful result includes:

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

If no records match, the tool returns a successful response with count set to 0 and an empty appointments array.

Example user requests:

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

Retrieves an appointment by its ID.

Input:

• appointment_id

Example:

{
  "appointment_id": "12"
}

A successful response includes the patient, doctor, appointment date, appointment time, reason, and status.

Example user request:

What is the status of appointment 12?

4. cancel_appointment

Cancels an existing appointment.

Input:

• appointment_id

Example:

{
  "appointment_id": "12"
}

Cancellation does not delete the appointment record. The server changes its status to:

cancelled

Keeping the record preserves appointment history.

Example user request:

Cancel appointment 12.

5. reschedule_appointment

Changes the date and time of an existing appointment.

Inputs:

• appointment_id
• new_appointment_date
• new_appointment_time

Example:

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

Cancelled appointments cannot be rescheduled by the current implementation.

Example user request:

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

Appointment Data Model

The REST backend is expected to store records similar to:

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

The server uses REST operations equivalent to:

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

find_appointments uses GET /appointments with query parameters such as:

patientName
doctorName
appointmentDate

Example Agent Workflow

A user may first ask:

Find my appointment with Dr. Mike.

The MCP client can invoke:

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

After the matching record and appointment ID are found, the user can say:

Move that appointment to September 21 at 10 AM.

The MCP client can then invoke:

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

This allows an AI agent to locate an appointment first instead of requiring the user to know the appointment ID.

Optional MCP Header Authentication

The server supports optional custom-header authentication through the MCP_REQUEST_HEADERS environment variable.

If the variable is not configured, custom-header authentication is disabled.

Simple header

Windows PowerShell:

$env:MCP_REQUEST_HEADERS="my-secret"

Linux/macOS/WSL:

export MCP_REQUEST_HEADERS="my-secret"

This configuration expects MCP requests to include a header named:

MCP_REQUEST_HEADERS

with the configured value.

Custom header name

The variable can also contain JSON:

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

The MCP client must then send:

X-API-Key: my-secret

The / and /health endpoints remain available without this custom authentication.

Security note: This project is a demonstration/learning implementation. A real healthcare application requires substantially stronger authentication, authorization, privacy controls, audit logging, secret management, data protection, and regulatory review before storing real patient information.

Deployment

The repository contains:

start.sh
run.sh

These scripts can be used for a Linux-based deployment.

start.sh installs the required Python packages into the deployment dependency directory.

run.sh starts the application with Uvicorn and listens on the PORT environment variable, defaulting to port 8080.

Required deployment environment variable:

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

Optional authentication:

MCP_REQUEST_HEADERS=your-secret

After deployment, the MCP endpoint will typically be:

https://YOUR-SERVER/mcp

and the health endpoint:

https://YOUR-SERVER/health

Testing the Server

Start the application:

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

Test the health endpoint:

curl http://127.0.0.1:8000/health

Expected response:

ok

Then configure an MCP-compatible client to connect to:

http://127.0.0.1:8000/mcp

The client should discover these five tools:

create_appointment
find_appointments
check_appointment_status
cancel_appointment
reschedule_appointment

Planned Improvements

Useful next steps include:

• Add doctor availability and time-slot lookup
• Prevent conflicting or double-booked appointments
• Add stronger date and time validation
• Add a production database
• Add OAuth or another production-grade authentication mechanism
• Add automated tests
• Add structured audit logging
• Integrate with a real calendar or scheduling provider
• Add production-grade patient identity and authorization controls

Development Status

This project is intended as an MCP development and learning project. The current appointment backend can later be replaced with a production scheduling service or database while preserving the MCP-facing tool interface.

Security and Healthcare Data

Do not use real patient information or protected health information (PHI) with an unsecured demonstration backend.

A production healthcare application may be subject to privacy, security, compliance, and data-retention requirements such as HIPAA in the United States.

Repository

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

License

No license has been specified for this repository yet. Add a LICENSE file before distributing or reusing the project under specific licensing terms.