FHIR MCP Server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@FHIR MCP Server search for patient John Doe"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
Patient - Demographics and patient information
AllergyIntolerance - Patient allergy and intolerance records
Condition - Medical conditions and diagnoses
Procedure - Medical procedures performed
Encounter - Patient encounters and visits
DiagnosticReport - Diagnostic reports and results
Observation - Clinical observations (vital signs, lab results)
Immunization - Immunization records
MedicationRequest - Medication prescriptions and requests
Appointment - Scheduled appointments
Installation
Prerequisites
Python 3.13 or higher
uvpackage manager (recommended) orpip
Setup
Clone the repository:
git clone <repository-url>
cd fhir-mcp-serverInstall dependencies using
uv:
uv syncOr using pip:
pip install -e .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_tokenThe .env file should contain:
FHIR_CLIENT_ID: Your OAuth2 client ID from the FHIR server providerFHIR_CLIENT_SECRET: Your OAuth2 client secret from the FHIR server providerFHIR_BASE_URL: The base URL of your FHIR R4 server endpointFHIR_TENANT_ID: (Optional) Your tenant ID, defaults to Oracle Cerner sandboxFHIR_SCOPE: (Optional) OAuth2 scopes, defaults to all supported resourcesFHIR_REQUEST_TIMEOUT: (Optional) Request timeout in seconds, default is 60
Configuration
Environment Variables
Variable | Description | Required | Default |
| OAuth2 client ID for authentication | Yes | None |
| OAuth2 client secret for authentication | Yes | None |
| Base URL of the FHIR server | No |
|
| Tenant ID for your FHIR server instance | No |
|
| OAuth2 token endpoint URL | No | Auto-generated from tenant ID |
| OAuth2 scopes (space-separated) | No | All supported resources |
| Request timeout in seconds | No |
|
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:
Create a CernerCare Account
Sign up at Oracle Cerner Code Console
Complete the account registration process
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
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
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 resourcessystem/Observation.rs- Read access to observation resourcessystem/Condition.rs- Read access to condition resourcessystem/Procedure.rs- Read access to procedure resourcessystem/Encounter.rs- Read access to encounter resourcessystem/DiagnosticReport.rs- Read access to diagnostic reportssystem/AllergyIntolerance.rs- Read access to allergy informationsystem/Immunization.rs- Read access to immunization recordssystem/MedicationRequest.rs- Read access to medication requestssystem/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/tokenDefault 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.pyOr if using uv:
uv run python fhir-mcp-server.pyUsing 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 IDsearch_patients_by_name- Search patients by given/family namesearch_patients_by_identifier- Search by identifier (MRN, SSN, etc.)search_patients_by_birthdate- Search by birth datesearch_patients_by_phone- Search by phone numbersearch_patients_by_email- Search by email addresssearch_patients_by_address- Search by address components
Clinical Data Tools
get_allergy_by_id/get_patient_allergies- Allergy informationget_condition_by_id/get_patient_conditions- Medical conditionsget_procedure_by_id/get_patient_procedures- Proceduresget_observation_by_id/get_patient_observations- Observationsget_patient_vital_signs- Vital signs specificallyget_patient_lab_results- Laboratory resultsget_immunization_by_id/get_patient_immunizations- Immunizations
Diagnostic & Medication Tools
get_diagnostic_report_by_id/get_patient_diagnostic_reports- Diagnostic reportsget_medication_request_by_id/get_patient_medication_requests- Medications
Encounter & Appointment Tools
get_encounter_by_id/get_patient_encounters- Patient encountersget_appointment_by_id/get_patient_appointments- Appointmentssearch_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 syncYour 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.jsonVerify 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_TIMEOUTin your.envfile or Claude Desktop configDefault is 60 seconds, try 120 or higher for slow servers
Security Considerations
Credential Management:
Never commit your
.envfile or credentials to version controlStore
FHIR_CLIENT_IDandFHIR_CLIENT_SECRETsecurelyUse 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 examplesAdding New FHIR Resources
To add support for additional FHIR resources:
Add a new tool function decorated with
@mcp.tool()Use the
make_fhir_request()helper functionFollow the existing pattern for parameters and return types
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
Built with FastMCP
Implements FHIR R4 standard
Designed for Oracle Millennium Platform APIs
Available Tools
29 toolsget_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
Scored across 29 tools
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.
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.
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.
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
Related MCP Connectors
Securely access and manage FHIR healthcare data stored in Medplum.
Query Health Gorilla FHIR patients, conditions, medications and lab results.
Read and write patients, facilities, medical documents, and consolidated FHIR records in Metriport.
Read Photon Health patients, prescriptions, orders, pharmacies and medications; screen interactions.
Related MCP Servers
- AlicenseNot gradedqualityNot gradedmaintenanceEnables 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
- AlicenseNot gradedqualityBmaintenanceEnables 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
- FlicenseAqualityDmaintenanceProvides read/write access to any FHIR-compliant healthcare API with built-in validation, supporting resource management, search operations, and granular permissions through natural language.51-
- AlicenseAqualityBmaintenanceProvides 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.71,026 PyPI137Apache 2.0