Skip to main content
Glama
FHIR MCP Server

FHIR MCP Server

by sdesani

FHIR MCP Server

A Model Context Protocol (MCP) server for interacting with FHIR APIs, specifically designed for Oracle Millennium Platform APIs. This server provides comprehensive tools for accessing various FHIR resources including Patient records, Clinical data, and Administrative information.

Features

  • OAuth2 Authentication: Secure API access using bearer token authentication

  • Comprehensive FHIR Resources: Support for 10+ FHIR resource types

  • Patient Search: Multiple search capabilities (name, identifier, birthdate, phone, email, address)

  • Clinical Data: Access to allergies, conditions, procedures, observations, and immunizations

  • Medications & Diagnostics: Retrieve medication requests and diagnostic reports

  • Appointments & Encounters: Manage patient appointments and clinical encounters

  • Asynchronous Operations: Efficient async/await implementation for better performance

Related MCP server: FhirMCP

Supported FHIR Resources

  1. Patient - Demographics and patient information

  2. AllergyIntolerance - Patient allergy and intolerance records

  3. Condition - Medical conditions and diagnoses

  4. Procedure - Medical procedures performed

  5. Encounter - Patient encounters and visits

  6. DiagnosticReport - Diagnostic reports and results

  7. Observation - Clinical observations (vital signs, lab results)

  8. Immunization - Immunization records

  9. MedicationRequest - Medication prescriptions and requests

  10. Appointment - Scheduled appointments

Installation

Prerequisites

  • Python 3.13 or higher

  • uv package manager (recommended) or pip

Setup

  1. Clone the repository:

git clone <repository-url>
cd fhir-mcp-server
  1. Install dependencies using uv:

uv sync

Or using pip:

pip install -e .
  1. Configure environment variables:

Create a .env file in the project directory and set your FHIR server details:

FHIR_BASE_URL=https://your-fhir-server.com/r4
OAUTH_BEARER_TOKEN=your_oauth2_bearer_token

The .env file should contain:

  • FHIR_CLIENT_ID: Your OAuth2 client ID from the FHIR server provider

  • FHIR_CLIENT_SECRET: Your OAuth2 client secret from the FHIR server provider

  • FHIR_BASE_URL: The base URL of your FHIR R4 server endpoint

  • FHIR_TENANT_ID: (Optional) Your tenant ID, defaults to Oracle Cerner sandbox

  • FHIR_SCOPE: (Optional) OAuth2 scopes, defaults to all supported resources

  • FHIR_REQUEST_TIMEOUT: (Optional) Request timeout in seconds, default is 60

Configuration

Environment Variables

Variable

Description

Required

Default

FHIR_CLIENT_ID

OAuth2 client ID for authentication

Yes

None

FHIR_CLIENT_SECRET

OAuth2 client secret for authentication

Yes

None

FHIR_BASE_URL

Base URL of the FHIR server

No

https://fhir-ehr.cerner.com/r4

FHIR_TENANT_ID

Tenant ID for your FHIR server instance

No

ec2458f2-1e24-41c8-b71b-0e701af7583d

FHIR_TOKEN_ENDPOINT

OAuth2 token endpoint URL

No

Auto-generated from tenant ID

FHIR_SCOPE

OAuth2 scopes (space-separated)

No

All supported resources

FHIR_REQUEST_TIMEOUT

Request timeout in seconds

No

60.0

OAuth2 Authentication

This server uses OAuth 2.0 Client Credentials flow for system-to-system authentication, following Oracle Cerner's SMART Backend Services specification.

Application Registration

Before using this server, you must register your application with Oracle Cerner to obtain client credentials:

  1. Create a CernerCare Account

  2. Register Your Application

    • Log in to the Code Console

    • Navigate to "My Applications" and click "Register New Application"

    • Choose application type:

      • System - For backend services and automated systems

      • Confidential - For applications that can securely store credentials

    • Provide application details:

      • Application name

      • Description

      • Redirect URIs (not required for client credentials flow)

    • Complete the registration process

  3. Obtain Credentials

    • After registration, you'll receive:

      • Client ID - Your application's unique identifier

      • Client Secret - Managed through Cerner Central system accounts

    • Store these credentials securely

  4. Configure FHIR Scopes

    Note: Scope format varies based on type of token requested. Below scopes format are for SMART V2 Token:

    Request the following system-level scopes for your application (SMART v1 format):

    • system/Patient.rs - Read access to patient resources

    • system/Observation.rs - Read access to observation resources

    • system/Condition.rs - Read access to condition resources

    • system/Procedure.rs - Read access to procedure resources

    • system/Encounter.rs - Read access to encounter resources

    • system/DiagnosticReport.rs - Read access to diagnostic reports

    • system/AllergyIntolerance.rs - Read access to allergy information

    • system/Immunization.rs - Read access to immunization records

    • system/MedicationRequest.rs - Read access to medication requests

    • system/Appointment.rs - Read access to appointments

Token Endpoint

The server automatically manages OAuth 2.0 tokens using Oracle Cerner's token endpoint:

https://authorization.cerner.com/tenants/{TENANT_ID}/hosts/fhir-ehr.cerner.com/protocols/oauth2/profiles/smart-v1/token

Default tenant ID: ec2458f2-1e24-41c8-b71b-0e701af7583d (Oracle Cerner Sandbox)

Automatic Token Management

The server automatically:

  • Requests access tokens using client credentials on first API call

  • Caches tokens until expiry

  • Refreshes tokens automatically when needed (with 5-minute buffer before expiry)

  • Handles token errors gracefully

Additional Resources

For more information about Oracle Cerner's authorization framework:

Usage

Running the Server

Run the MCP server using:

python fhir-mcp-server.py

Or if using uv:

uv run python fhir-mcp-server.py

Using with Claude Desktop or Cursor

For Claude Desktop:

Add the following configuration to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "fhir": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "fastmcp",
        "fastmcp",
        "run",
        "/absolute/path/to/fhir-mcp-server/fhir-mcp-server.py"
      ],
      "env": {
        "FHIR_CLIENT_ID": "your_client_id",
        "FHIR_CLIENT_SECRET": "your_client_secret",
        "FHIR_BASE_URL": "https://fhir-ehr.cerner.com/r4",
        "FHIR_TENANT_ID": "your_tenant_id"
      }
    }
  }
}

Important: Replace /absolute/path/to/fhir-mcp-server/fhir-mcp-server.py with the actual full path to the script!

For Cursor IDE:

Add the same configuration to Cursor's MCP settings. See QUICKSTART.md for detailed Cursor-specific instructions including:

  • Where to find Cursor's MCP configuration

  • UI-based setup options

  • Cursor-specific troubleshooting

Available Tools

Patient Tools

  • get_patient_by_id - Retrieve a patient by ID

  • search_patients_by_name - Search patients by given/family name

  • search_patients_by_identifier - Search by identifier (MRN, SSN, etc.)

  • search_patients_by_birthdate - Search by birth date

  • search_patients_by_phone - Search by phone number

  • search_patients_by_email - Search by email address

  • search_patients_by_address - Search by address components

Clinical Data Tools

  • get_allergy_by_id / get_patient_allergies - Allergy information

  • get_condition_by_id / get_patient_conditions - Medical conditions

  • get_procedure_by_id / get_patient_procedures - Procedures

  • get_observation_by_id / get_patient_observations - Observations

  • get_patient_vital_signs - Vital signs specifically

  • get_patient_lab_results - Laboratory results

  • get_immunization_by_id / get_patient_immunizations - Immunizations

Diagnostic & Medication Tools

  • get_diagnostic_report_by_id / get_patient_diagnostic_reports - Diagnostic reports

  • get_medication_request_by_id / get_patient_medication_requests - Medications

Encounter & Appointment Tools

  • get_encounter_by_id / get_patient_encounters - Patient encounters

  • get_appointment_by_id / get_patient_appointments - Appointments

  • search_appointments_by_date - Search appointments by date

Utility Tools

  • get_fhir_capability_statement - Get FHIR server capabilities

Example Usage

Example 1: Search for a Patient

# Search for patients by name
result = await search_patients_by_name(
    given_name="John",
    family_name="Doe"
)

Example 2: Get Patient's Medical History

# Get patient's conditions
conditions = await get_patient_conditions(
    patient_id="12345",
    clinical_status="active"
)

# Get patient's allergies
allergies = await get_patient_allergies(
    patient_id="12345"
)

# Get patient's vital signs
vitals = await get_patient_vital_signs(
    patient_id="12345",
    date="2024-01-01"
)

Example 3: Retrieve Appointments

# Get upcoming appointments for a patient
appointments = await get_patient_appointments(
    patient_id="12345",
    status="booked",
    date="ge2024-01-01"  # Greater than or equal to date
)

API Reference Documentation

This server implements tools based on the following Oracle Millennium Platform API documentation:

FHIR Standards

This server follows the FHIR R4 specification for resource structures and search parameters.

Error Handling

The server will raise HTTP exceptions for:

  • Authentication failures (401 Unauthorized)

  • Missing resources (404 Not Found)

  • Server errors (500 Internal Server Error)

  • Invalid requests (400 Bad Request)

All exceptions include detailed error messages from the FHIR server response.

Troubleshooting

ModuleNotFoundError: No module named 'httpx' (or other dependencies)

Problem: Claude Desktop shows ModuleNotFoundError when trying to load the MCP server.

Solution: Make sure you've installed dependencies first:

cd /Users/sdesani/Work/fhir-mcp-server
uv sync

Your Claude Desktop config should use the fastmcp run pattern:

{
  "command": "uv",
  "args": [
    "run",
    "--with",
    "fastmcp",
    "fastmcp",
    "run",
    "/absolute/path/to/fhir-mcp-server/fhir-mcp-server.py"
  ]
}

This uses uv run --with fastmcp to dynamically install FastMCP, then runs your script which will use the installed dependencies from your project's .venv.

Other Common Issues

Server not appearing in Claude Desktop:

  • Restart Claude Desktop after updating the config

  • Check for JSON syntax errors in claude_desktop_config.json

  • Verify the file path is absolute (starts with /)

401 Unauthorized errors:

  • Verify your OAuth token is valid and not expired

  • Check the token has the correct scopes/permissions

Timeout errors:

  • Increase FHIR_REQUEST_TIMEOUT in your .env file or Claude Desktop config

  • Default is 60 seconds, try 120 or higher for slow servers

Security Considerations

  • Credential Management:

    • Never commit your .env file or credentials to version control

    • Store FHIR_CLIENT_ID and FHIR_CLIENT_SECRET securely

    • Use environment variables or secure credential management systems

    • Rotate credentials regularly according to your organization's security policies

  • OAuth 2.0 Security:

    • The server uses OAuth 2.0 Client Credentials flow for secure system-to-system authentication

    • Tokens are automatically cached and refreshed

    • Follow the Application Registration steps to obtain valid credentials

  • HTTPS Only: Always use HTTPS endpoints for production FHIR servers

  • Scope Management:

    • Request only the minimum required scopes for your application

    • Review and update scopes as your application requirements change

    • See Application Registration for available scopes

  • PHI Protection:

    • Be mindful that FHIR resources contain Protected Health Information (PHI)

    • Ensure compliance with healthcare data privacy regulations (HIPAA, GDPR, etc.)

    • Implement appropriate access controls and audit logging

    • Follow your organization's data handling policies

  • SMART Compliance:

    • This server follows the SMART Backend Services specification

    • Ensures secure healthcare application integration

Development

Project Structure

fhir-mcp-server/
├── fhir-mcp-server.py   # MCP server implementation
├── pyproject.toml       # Project dependencies and metadata
├── .env                 # Your local configuration (not committed)
├── .gitignore          # Git ignore rules
├── README.md           # This file
├── QUICKSTART.md       # Quick start guide
└── EXAMPLES.md         # Usage examples

Adding New FHIR Resources

To add support for additional FHIR resources:

  1. Add a new tool function decorated with @mcp.tool()

  2. Use the make_fhir_request() helper function

  3. Follow the existing pattern for parameters and return types

  4. Update this README with the new tool information

Testing

Test the server by running it and connecting through an MCP client like Cursor or using the MCP Inspector tool.

License

[Add your license information here]

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

For issues related to:

  • FHIR Server: Contact your FHIR server administrator

  • Oracle Millennium Platform: Refer to Oracle documentation

  • This MCP Server: Open an issue in this repository

Additional Documentation

  • QUICKSTART.md - Quick start guide with setup instructions for Claude Desktop and Cursor

  • EXAMPLES.md - Comprehensive usage examples

Acknowledgments

Available Tools

29 tools
get_allergy_by_idB

Retrieve a specific allergy intolerance by ID.

Args: allergy_id: The FHIR AllergyIntolerance ID

Returns: Dictionary containing the allergy intolerance information

Inputs: allergy_id (required). Returns: object

get_appointment_by_idB

Retrieve a specific appointment by ID.

Args: appointment_id: The FHIR Appointment ID

Returns: Dictionary containing the appointment information

Inputs: appointment_id (required). Returns: object

get_condition_by_idB

Retrieve a specific condition by ID.

Args: condition_id: The FHIR Condition ID

Returns: Dictionary containing the condition information

Inputs: condition_id (required). Returns: object

get_diagnostic_report_by_idB

Retrieve a specific diagnostic report by ID.

Args: report_id: The FHIR DiagnosticReport ID

Returns: Dictionary containing the diagnostic report information

Inputs: report_id (required). Returns: object

get_encounter_by_idB

Retrieve a specific encounter by ID.

Args: encounter_id: The FHIR Encounter ID

Returns: Dictionary containing the encounter information

Inputs: encounter_id (required). Returns: object

get_fhir_capability_statementA

Retrieve the FHIR server's capability statement (metadata). This provides information about the server's capabilities and supported resources.

Returns: Dictionary containing the FHIR server capabilities

Inputs: no named parameters. Returns: object

get_immunization_by_idA

Retrieve a specific immunization by ID.

Args: immunization_id: The FHIR Immunization ID

Returns: Dictionary containing the immunization information

Inputs: immunization_id (required). Returns: object

get_medication_request_by_idA

Retrieve a specific medication request by ID.

Args: medication_request_id: The FHIR MedicationRequest ID

Returns: Dictionary containing the medication request information

Inputs: medication_request_id (required). Returns: object

get_observation_by_idB

Retrieve a specific observation by ID.

Args: observation_id: The FHIR Observation ID

Returns: Dictionary containing the observation information

Inputs: observation_id (required). Returns: object

get_patient_allergiesA

Retrieve allergies for a specific patient.

Args: patient_id: The FHIR patient ID clinical_status: Optional filter by clinical status (active, inactive, resolved)

Returns: Dictionary containing the patient's allergies

Inputs: patient_id (required), clinical_status. Returns: object

get_patient_appointmentsA

Retrieve appointments for a specific patient.

Args: patient_id: The FHIR patient ID date: Optional filter by date (YYYY-MM-DD format, automatically formatted with time component) status: Optional filter by status (proposed, pending, booked, arrived, fulfilled, cancelled)

Returns: Dictionary containing the patient's appointments

Inputs: patient_id (required), date, status. Returns: object

get_patient_by_idA

Retrieve a specific patient by their FHIR patient ID.

Args: patient_id: The FHIR patient ID to retrieve

Returns: Dictionary containing the patient information

Inputs: patient_id (required). Returns: object

get_patient_conditionsA

Retrieve conditions for a specific patient.

Args: patient_id: The FHIR patient ID clinical_status: Optional filter by clinical status (active, inactive, resolved) category: Optional filter by category (problem-list-item, encounter-diagnosis)

Returns: Dictionary containing the patient's conditions

Inputs: patient_id (required), clinical_status, category. Returns: object

get_patient_diagnostic_reportsB

Retrieve diagnostic reports for a specific patient.

Args: patient_id: The FHIR patient ID category: Optional filter by category (LAB, RAD, etc.) date: Optional filter by date (YYYY-MM-DD format or date range) status: Optional filter by status (registered, partial, final, corrected)

Returns: Dictionary containing the patient's diagnostic reports

Inputs: patient_id (required), category, date, status. Returns: object

get_patient_encountersA

Retrieve encounters for a specific patient.

Args: patient_id: The FHIR patient ID date: Optional filter by date (YYYY-MM-DD format or date range) status: Optional filter by status (planned, arrived, in-progress, finished) encounter_class: Optional filter by class (ambulatory, emergency, inpatient)

Returns: Dictionary containing the patient's encounters

Inputs: patient_id (required), date, status, encounter_class. Returns: object

get_patient_immunizationsA

Retrieve immunizations for a specific patient.

Args: patient_id: The FHIR patient ID date: Optional filter by date (YYYY-MM-DD format or date range) status: Optional filter by status (completed, not-done)

Returns: Dictionary containing the patient's immunizations

Inputs: patient_id (required), date, status. Returns: object

get_patient_lab_resultsC

Retrieve laboratory observations for a specific patient.

Args: patient_id: The FHIR patient ID date: Optional filter by date (YYYY-MM-DD format or date range)

Returns: Dictionary containing the patient's lab results

Inputs: patient_id (required), date. Returns: object

get_patient_medication_requestsA

Retrieve medication requests for a specific patient.

Args: patient_id: The FHIR patient ID status: Optional filter by status (active, completed, cancelled) intent: Optional filter by intent (order, plan, proposal)

Returns: Dictionary containing the patient's medication requests

Inputs: patient_id (required), status, intent. Returns: object

get_patient_observationsA

Retrieve observations for a specific patient.

Args: patient_id: The FHIR patient ID category: Optional filter by category (vital-signs, laboratory, etc.) code: Optional filter by observation code (LOINC code) date: Optional filter by date (YYYY-MM-DD format or date range)

Returns: Dictionary containing the patient's observations

Inputs: patient_id (required), category, code, date. Returns: object

get_patient_proceduresA

Retrieve procedures for a specific patient.

Args: patient_id: The FHIR patient ID date: Optional filter by date (YYYY-MM-DD format or date range) status: Optional filter by status (preparation, in-progress, completed)

Returns: Dictionary containing the patient's procedures

Inputs: patient_id (required), date, status. Returns: object

get_patient_vital_signsA

Retrieve vital signs observations for a specific patient.

Args: patient_id: The FHIR patient ID date: Optional filter by date (YYYY-MM-DD format or date range)

Returns: Dictionary containing the patient's vital signs

Inputs: patient_id (required), date. Returns: object

get_procedure_by_idC

Retrieve a specific procedure by ID.

Args: procedure_id: The FHIR Procedure ID

Returns: Dictionary containing the procedure information

Inputs: procedure_id (required). Returns: object

search_appointments_by_dateA

Search for appointments by date.

Args: date: Appointment date (YYYY-MM-DD format, automatically formatted with time component) status: Optional filter by status (proposed, pending, booked, arrived, fulfilled, cancelled)

Returns: Dictionary containing the appointments

Inputs: date (required), status. Returns: object

search_patients_by_addressB

Search for patients by address components.

Args: postal_code: Patient's postal/ZIP code city: Patient's city state: Patient's state

Returns: Dictionary containing the search results

Inputs: postal_code, city, state. Returns: object

search_patients_by_birthdateA

Search for patients by birth date.

Args: birthdate: Patient's birth date in YYYY-MM-DD format

Returns: Dictionary containing the search results

Inputs: birthdate (required). Returns: object

search_patients_by_emailB

Search for patients by email address.

Args: email: Patient's email address

Returns: Dictionary containing the search results

Inputs: email (required). Returns: object

search_patients_by_identifierA

Search for patients by identifier (e.g., MRN, SSN).

Args: identifier_type: Type of identifier (e.g., "MR", "SS") identifier_value: The identifier value to search for

Returns: Dictionary containing the search results

Inputs: identifier_type (required), identifier_value (required). Returns: object

search_patients_by_nameC

Search for patients by name using FHIR search parameters.

Args: given_name: Patient's given (first) name family_name: Patient's family (last) name

Returns: Dictionary containing the search results

Inputs: given_name, family_name. Returns: object

search_patients_by_phoneC

Search for patients by phone number.

Args: phone_number: Patient's phone number

Returns: Dictionary containing the search results

Inputs: phone_number (required). Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 29 tools

    Disambiguation4/5

    Most tools target distinct resources, with clear patterns like get_<resource>_by_id and get_patient_<resource>. However, there is potential overlap between get_patient_lab_results, get_patient_vital_signs, and get_patient_observations, as lab results and vital signs are subsets of observations. Descriptions help distinguish them, but an agent could still be confused.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern using snake_case. get_ and search_ prefixes are used appropriately, and resource names are pluralized uniformly. No mixed conventions or irregular naming.

    Tool Count5/5

    With 29 tools, the server covers a wide range of FHIR resources and search capabilities without being overwhelming. The count is well-scoped for a FHIR client, providing both individual resource retrieval by ID and patient-centric queries, plus a capability statement.

    Completeness4/5

    The tool set covers the most common FHIR resources and operations (read, search by patient) effectively. Minor gaps exist, such as missing direct access to Medication or Practitioner resources, but these are not critical for a patient-centric server. Overall, it provides a complete surface for typical use cases.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      Not graded
      maintenance
      Enables seamless integration with FHIR APIs for healthcare applications, allowing users to search, retrieve, create, update, and analyze clinical information through natural language interactions. Supports SMART-on-FHIR authentication and works with various healthcare systems like EPIC and HAPI FHIR servers.
      Apache 2.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables LLMs to securely interact with FHIR healthcare servers and HL7 terminology services. Provides comprehensive healthcare data operations with built-in PHI protection, audit logging, and SMART on FHIR authentication.
      MIT
    • F
      license
      A
      quality
      D
      maintenance
      Provides read/write access to any FHIR-compliant healthcare API with built-in validation, supporting resource management, search operations, and granular permissions through natural language.
      5
      1
      -
    • A
      license
      A
      quality
      B
      maintenance
      Provides seamless integration with FHIR APIs, enabling AI/LLM tools to search, retrieve, and analyze clinical healthcare data with support for SMART-on-FHIR authentication and multiple transport protocols.
      7
      1,026 PyPI
      137
      Apache 2.0