Skip to main content
Glama

FHIR Progressive Discovery MCP Server

by CaseMark
GitHub
Python
OverviewInspectNewEndpointsSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

FHIR Progressive Discovery MCP Server

A sophisticated FastMCP-based server that provides progressive discovery of FHIR (Fast Healthcare Interoperability Resources) operations, inspired by Klavis AI architecture patterns.

🎯 Key Features

  • Progressive Discovery: Resources are discovered based on user intent, not loaded all at once

  • 11 Resource Groups: Clinical, Administrative, Workflow, Financial, and more

  • Native PDF Conversion: Convert medical PDFs directly to FHIR DocumentReference resources

  • Format Conversion: Transform between JSON, XML, and YAML formats

  • Built on FastMCP: Modern, type-safe Python MCP server framework

  • Pydantic v2 Validation: Robust FHIR resource validation using fhir.resources

🏗️ Architecture

Progressive Discovery Model

Instead of exposing 100+ FHIR resources at once, this server organizes resources into logical groups and progressively discovers them based on context:

User Intent → Discover Groups → Explore Group → Use Specific Resources

Discovery Flow:

  1. discover_resource_groups(intent="patient care") → Returns relevant groups

  2. explore_resource_group(group_id="clinical") → Shows resources in that group

  3. get_resource_schema(resource_type="Patient") → Get specific resource structure

  4. create_resource(...) → Work with the resource

Resource Groups

Group

Resources

Priority

Clinical

Condition, Observation, Procedure, Medication, Immunization, AllergyIntolerance, DiagnosticReport

1

Administrative

Patient, Practitioner, Organization, Location, HealthcareService

1

Workflow

Encounter, Appointment, EpisodeOfCare, Task, ServiceRequest, CarePlan

2

Financial

Coverage, Claim, Invoice, PaymentNotice, Account, ExplanationOfBenefit

3

Diagnostics

ImagingStudy, Media, BodyStructure, MolecularSequence

2

Medications

Medication, MedicationAdministration, MedicationDispense, MedicationRequest

2

Documents

DocumentReference, DocumentManifest, Composition

2

Clinical Reasoning

PlanDefinition, ActivityDefinition, Questionnaire, RiskAssessment

3

Research

ResearchStudy, ResearchSubject, Evidence, Citation

4

Terminology

CodeSystem, ValueSet, ConceptMap, NamingSystem

4

Security

AuditEvent, Provenance, Consent, Permission

3

🚀 Installation

# Clone or download the repository cd "FHIR MCP" # Install dependencies pip install -r requirements.txt # Or use the project config pip install -e .

📖 Usage

Starting the Server

python fhir_mcp_server.py

MCP Tools Available

1. Discovery Tools

discover_resource_groups(intent: str)

  • Entry point for progressive discovery

  • Returns resource groups ranked by relevance to your intent

# Example intents: "patient care" # → Clinical, Administrative groups "billing" # → Financial, Administrative groups "scheduling" # → Workflow, Administrative groups "research study" # → Research, Clinical groups

explore_resource_group(group_id: str)

  • Deep dive into a specific group

  • Shows all resources and available operations

list_all_resource_groups()

  • Complete overview of all groups

2. Resource Operations

get_resource_schema(resource_type: str)

  • Get Pydantic schema for any FHIR resource

  • Shows required fields, types, and structure

create_resource(resource_type: str, resource_data: dict)

  • Create and validate FHIR resources

  • Returns validated FHIR JSON

validate_resource(resource_json: str)

  • Validate existing FHIR JSON against schema

convert_between_formats(resource_data: str, input_format: str, output_format: str)

  • Convert between JSON, XML, YAML formats

  • Formats: "json", "xml", "yaml"

search_resources(resource_type: str, search_params: dict)

  • Validate search parameters against schema

  • Prepares queries for FHIR server execution

3. PDF Conversion Tools

convert_pdf_to_fhir(pdf_path: str, document_type: str, patient_reference: str)

  • Convert medical PDFs to FHIR DocumentReference

  • Extract text and metadata

  • Basic clinical data extraction

Document Types:

  • clinical_note - Outpatient notes

  • lab_report - Laboratory results

  • discharge_summary - Hospital discharge docs

  • prescription - Medication prescriptions

batch_convert_pdfs_to_fhir(pdf_directory: str, document_type: str, patient_reference: str)

  • Batch process entire directories of PDFs

4. Utility Tools

get_fhir_version_info()

  • Check supported FHIR versions and features

💡 Example Workflows

Workflow 1: Create a Patient Resource

# 1. Discover what's available for patient management discover_resource_groups(intent="patient management") # → Returns: Administrative, Clinical groups # 2. Explore the administrative group explore_resource_group(group_id="administrative") # → Shows: Patient, Practitioner, Organization... # 3. Get Patient schema get_resource_schema(resource_type="Patient") # → Returns: Full Patient schema with required fields # 4. Create a patient create_resource( resource_type="Patient", resource_data={ "resourceType": "Patient", "active": True, "name": [{ "use": "official", "family": "Doe", "given": ["John"] }], "gender": "male", "birthDate": "1990-01-01" } ) # → Returns: Validated Patient FHIR resource

Workflow 2: Convert Lab Report PDF to FHIR

# Convert a single lab report convert_pdf_to_fhir( pdf_path="/path/to/lab_report.pdf", document_type="lab_report", patient_reference="Patient/12345" ) # → Returns: DocumentReference resource with extracted text # Batch convert all PDFs in a folder batch_convert_pdfs_to_fhir( pdf_directory="/path/to/medical_records/", document_type="clinical_note", patient_reference="Patient/12345" ) # → Processes all PDFs and returns results

Workflow 3: Create and Convert Observation

# 1. Discover clinical resources discover_resource_groups(intent="patient vitals") # → Returns: Clinical group # 2. Create an Observation create_resource( resource_type="Observation", resource_data={ "resourceType": "Observation", "status": "final", "code": { "coding": [{ "system": "http://loinc.org", "code": "85354-9", "display": "Blood pressure" }] }, "subject": {"reference": "Patient/123"}, "valueQuantity": { "value": 120, "unit": "mmHg" } } ) # → Returns: Validated Observation in JSON # 3. Convert to XML convert_between_formats( resource_data='{"resourceType": "Observation", ...}', input_format="json", output_format="xml" ) # → Returns: XML representation

🧠 Progressive Discovery Benefits

  1. Reduced Context Window Usage: Load only what you need, when you need it

  2. Intent-Based Discovery: Find resources based on your use case, not alphabetically

  3. Scalable: Works with 100+ FHIR resources without overwhelming the agent

  4. Grouped Operations: Related resources are discovered together

  5. Lazy Loading: Resources are only instantiated when accessed

🔧 Technical Details

FHIR Versions Supported

  • R5 (default) - FHIR version 5.0.0

  • R4B - FHIR version 4.3.0

  • STU3 - FHIR version 3.0.2

Dependencies

  • FastMCP: Modern MCP server framework

  • fhir.resources: Official Python FHIR resources with Pydantic v2

  • PyPDF2: PDF text extraction

  • Pydantic: Data validation and serialization

Resource Validation

All resources are validated using:

  • Pydantic v2 models from fhir.resources

  • FHIR specification compliance

  • Required field checking

  • Type validation

  • Cardinality constraints

📚 FHIR Resources

This server supports all standard FHIR R5 resources including:

Clinical: AllergyIntolerance, CarePlan, CareTeam, ClinicalImpression, Condition, DetectedIssue, DiagnosticReport, FamilyMemberHistory, Goal, Immunization, MedicationAdministration, MedicationDispense, MedicationRequest, MedicationStatement, Observation, Procedure, RiskAssessment, Specimen

Administrative: Patient, Practitioner, PractitionerRole, Organization, Location, HealthcareService, Endpoint, Person, Group, RelatedPerson

Workflow: Appointment, AppointmentResponse, Schedule, Slot, Encounter, EpisodeOfCare, Flag, ServiceRequest, Task, Communication, CommunicationRequest

Financial: Account, ChargeItem, Claim, ClaimResponse, Coverage, CoverageEligibilityRequest, CoverageEligibilityResponse, EnrollmentRequest, ExplanationOfBenefit, Invoice, PaymentNotice, PaymentReconciliation

And many more...

🎨 Design Philosophy

This server follows the Klavis progressive discovery pattern:

  • Intent-driven: Start with user intent, not resource lists

  • Layered discovery: Groups → Resources → Operations

  • Context-aware: Relevance scoring based on use case

  • Scalable architecture: Handles large resource sets efficiently

🤝 Contributing

Contributions welcome! Areas for enhancement:

  • Advanced NLP for PDF extraction

  • FHIR server connectivity (HAPI, Azure FHIR)

  • HL7 v2 message conversion

  • CDA document parsing

  • SMART on FHIR integration

📄 License

MIT License

🔗 References

Built with surgical precision for the gods of programming ⚡️

This server cannot be installed

-
security - not tested
F
license - not found
-
quality - not tested

How are these scores calculated?

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

Enables progressive discovery and management of FHIR healthcare resources through intent-based grouping, with support for creating/validating resources, converting between formats, and transforming medical PDFs to FHIR DocumentReference resources.

  1. 🎯 Key Features
    1. 🏗️ Architecture
      1. Progressive Discovery Model
      2. Resource Groups
    2. 🚀 Installation
      1. 📖 Usage
        1. Starting the Server
        2. MCP Tools Available
      2. 💡 Example Workflows
        1. Workflow 1: Create a Patient Resource
        2. Workflow 2: Convert Lab Report PDF to FHIR
        3. Workflow 3: Create and Convert Observation
      3. 🧠 Progressive Discovery Benefits
        1. 🔧 Technical Details
          1. FHIR Versions Supported
          2. Dependencies
          3. Resource Validation
        2. 📚 FHIR Resources
          1. 🎨 Design Philosophy
            1. 🤝 Contributing
              1. 📄 License
                1. 🔗 References

                  New MCP Servers

                  MCP directory API

                  We provide all the information about MCP servers via our MCP API.

                  curl -X GET 'https://glama.ai/api/mcp/v1/servers/CaseMark/FHIR-MCP'

                  If you have feedback or need assistance with the MCP directory API, please join our Discord server