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:

retrieve_archetype: Gets OpenEHR archetype definitions by clinical concept or ID
generate_aql: Creates AQL queries from natural language using archetype structure
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:

Calls retrieve_archetype(concept="blood_pressure") → Gets archetype structure
Calls generate_aql(query="last 15 blood pressure readings", archetype=..., patient_id="xyz") → Gets AQL
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

Clone the repository:

git clone <this-repo>
cd openehr-mcp

Create and activate virtual environment:

# Create virtual environment
python -m venv venv

# Activate virtual environment
# Windows:
.\venv\Scripts\Activate.ps1
# Linux/Mac:
source venv/bin/activate

Install dependencies:

pip install -r requirements.txt

Configure environment:

# Copy example config
cp .env.example .env

# Edit .env with your settings
notepad .env  # Windows

Verify setup:

python verify_setup.py

Start the server:

cd src
python main.py
# OR for development with auto-reload:
# python -m uvicorn main:app --host 0.0.0.0 --port 3000 --reload

🚀 Quick Setup for New Users

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

Clone the repository
Create your own virtual environment (the venv/ folder is not shared)
Install all dependencies from requirements.txt
Configure your environment with your own settings
Run the server

Complete setup commands:

# Windows PowerShell
git clone <repo-url>
cd openehr-mcp
python -m venv venv
.\venv\Scripts\Activate.ps1
pip install -r requirements.txt
cp .env.example .env
# Edit .env with your settings
cd src
python main.py

# Linux/Mac
git clone <repo-url>
cd openehr-mcp
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
# Edit .env with your settings
cd src
python main.py

Configuration

Edit .env file with your settings:

# Your IIS EHR API
EHR_API_BASE_URL=http://your-iis-server:8080/ehr-api
EHR_API_KEY=your_api_key

# OpenEHR CKM (optional)
CKM_API_URL=https://ckm.openehr.org/ckm
OPENEHR_CKM_API_KEY=your_ckm_key

# Local archetypes
ARCHETYPE_PATH=./templates

Usage

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

Retrieve archetype definitions
Generate AQL queries
Execute queries against an EHR system

Example Flow

User asks: "Give me last 15 readings for blood pressure for patient xyz"
LLM calls retrieve_archetype tool to get blood pressure archetype structure
LLM calls generate_aql tool to create an appropriate AQL query
LLM calls execute_ehr_query tool to run the query against the EHR system
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.

OpenEHR MCP Server