EHR Tools with MCP and FHIR

This project acts as a specialized server providing tools for Large Language Models (LLMs) and other AI agents to interact with Electronic Health Records (EHRs). It leverages theSMART on FHIRstandard for secure data access and theModel Context Protocol (MCP)to expose the tools.

Think of it as a secure gateway and toolkit enabling AI to safely access and analyze patient data from diverse EHR systems.
- SMART on FHIR Client (Implemented within this project):Connects securely to an EHR using the standard SMART App Launch framework. It extracts a wide range of patient information, including both structured data (like conditions, medications, labs) and unstructured clinical notes or attachments.
- MCP Server (This Project):Takes the extracted EHR data and makes it available through a set of powerful tools accessible via the Model Context Protocol. These tools allow external systems (like AI models) to query and analyze the data without needing direct access to the EHR itself.
- AI / LLM Interface (External Consumer):An AI agent or Large Language Model connects to the MCP Server and uses the provided tools to "ask questions" about the patient's record, perform searches, or run custom analyses.

The MCP Server offers several tools for interacting with the loaded EHR data:

- grep_record: Performs text or regular expression searches acrossallparts of the fetched record (structured FHIR data + text from notes/attachments). Ideal for finding keywords or specific mentions (e.g., "diabetes", "aspirin").
- query_record: Executes read-only SQLSELECTqueries directly against the structured FHIR data. Useful for precise lookups based on known FHIR resource structures (e.g., finding specific lab results by LOINC code).
- eval_record: Executes custom JavaScript code directly on the fetched data (FHIR resources + attachments). Offers maximum flexibility for complex calculations, combining data from multiple sources, or custom formatting.

This setup allows AI tools to leverage comprehensive EHR data through a standardized and secure interface.

(Developer setup and usage details can be found within the codebase and specific module documentation.)

This project offers different ways to fetch EHR data and expose it via MCP tools:

This project includes a self-contained web application that allows users to connect to their EHR via SMART on FHIR and fetch their data.

- ?brandTags=epic,sandbox: Shows brands tagged withepicORsandbox.
- ?brandTags=epic^dev: Shows brands tagged with bothepicANDdev.
- ?brandTags=epic^dev,sandbox^prod: Shows brands tagged with (epicANDdev) OR (sandboxANDprod).
- If the parameter is omitted, it defaults to showing brands tagged withprod.
- Example:.../ehr-connect?brandTags=hospital^us: Shows brands tagged withhospitalANDus.

- fhir: A dictionary where keys are FHIR resource types (e.g., "Patient") and values are arrays of the corresponding FHIR resources.
- attachments: An array of processed attachment objects, each including metadata (source resource, path, content type) and the content itself (contentBase64for raw data,contentPlaintextfor extracted text).

2. Local MCP Server via Stdio (src/cli.ts)

This mode is ideal for running the MCP server locally, often used with tools like Cursor or other command-line AI clients.

- Two-Step Process:
- Fetch Data to Database:First, run the command-line interface with the--create-dband--dbflags. This starts a temporary web server and uses the same SMART on FHIR web client logic described above to fetch data. Instead of sending the data viapostMessage, it saves theClientFullEHRdata into a local SQLite database file.

# Example: Fetch data and save to data/my_record.sqlite bun run src/cli.ts --create-db --db ./data/my_record.sqlite

# Example: Start the MCP server using the saved data bun run src/cli.ts --db ./data/my_record.sqlite

- Configuration (config..json):This process relies on a configuration file (e.g.,config.epicsandbox.json) which defines available EHR brands/endpoints in abrandFilesarray. Each entry in this array specifies the brand's details, including: