OpenEHR MCP Server

A Model Context Protocol (MCP) server that enables LLMs to interact with OpenEHR backends, including:

• OpenEHR Clinical Knowledge Manager (CKM) for standard archetypes

• Custom EHR APIs hosted on IIS server connected to on-premise EHR databases

• Local archetype resources (.adl/.opt files)

Architecture Overview

The server provides three main MCP tools that work together:

1. retrieve_archetype: Gets OpenEHR archetype definitions by clinical concept or ID

2. generate_aql: Creates AQL queries from natural language using archetype structure

3. execute_ehr_query: Executes AQL against your on-premise EHR database via IIS API

Example Workflow

User Query: "Give me last 15 readings for blood pressure for patient xyz"

LLM Flow:

1. Calls retrieve_archetype(concept="blood_pressure") → Gets archetype structure

2. Calls generate_aql(query="last 15 blood pressure readings", archetype=..., patient_id="xyz") → Gets AQL

3. Calls execute_ehr_query(aql=..., patient_id="xyz") → Returns patient data

Quick Start

Prerequisites

• Python 3.8+

• Access to your IIS-hosted EHR API

• Optional: OpenEHR CKM API access

Installation

1. Clone the repository:

2. Create and activate virtual environment:

3. Install dependencies:

4. Configure environment:

5. Verify setup:

6. Start the server:

🚀 Quick Setup for New Users

If someone shares this repo with you, here's what you need to do:

1. Clone the repository

2. Create your own virtual environment (the venv/ folder is not shared)

3. Install all dependencies from requirements.txt

4. Configure your environment with your own settings

5. Run the server

Complete setup commands:

Configuration

Edit .env file with your settings:

Usage

The MCP server exposes tools that can be used by an LLM to:

1. Retrieve archetype definitions

2. Generate AQL queries

3. Execute queries against an EHR system

Example Flow

1. User asks: "Give me last 15 readings for blood pressure for patient xyz"

2. LLM calls retrieve_archetype tool to get blood pressure archetype structure

3. LLM calls generate_aql tool to create an appropriate AQL query

4. LLM calls execute_ehr_query tool to run the query against the EHR system

5. Results are returned to the user

Communication Protocols

This MCP server uses Streamable HTTP as its primary communication protocol, allowing for efficient transfer of potentially large medical datasets between the LLM and the EHR systems.