openEHR MCP Server
About
# openEHR MCP Server An MCP (Model Context Protocol) server designed to interface with openEHR REST APIs, specifically the EHRbase implementation. This server enables MCP clients like Claude Desktop to create compositions for openEHR templates and submit them to a server. For production grade EHR integrations you must…
Details
- License
- MIT
Explore
- List and retrieve openEHR templates
- Create, retrieve, list, and search EHRs
- Create, read, update, and delete compositions
- Execute ad-hoc AQL queries
- Prompt for capturing vital signs
- Docker-based deployment for easy setup
Setting up with Highlight
This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:
- Download and install Highlight from highlightai.com/download
- Navigate to the plugins tab and select "Add Custom Plugin"
-
Configure the plugin with the settings below
Plugin Name
openEHR MCP ServerCommand (node, npx, python, etc.)Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
- Enable "Start Automatically" if you want the plugin to start when Highlight launches
From the repository
A working Docker installation
Python 3 (this project was built with python 3.12, earlier versions might work)
A Python virtual environment (pip, conda or uv)
Install the required dependencies in your Python environment:
pip install -r requirements.txt
The easiest way to get started is to use the pre-built Docker image available on Docker Hub.
Ensure you have a running EHRbase server. For running one locally, see below.
Edit your Claude Desktop configuration file (claude_desktop_config.json) and add an "openEHR" configuration block inside the "mcpServers" section.
This file can usually be found in the following locations:
On macOS: ~/Library/Application Support/Claude
On Windows: %APPDATA%\Claude
{
"mcpServers": {
"openEHR": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"--network=host",
"-e","EHRBASE_URL=http://localhost:8080/ehrbase/rest",
"-e","EHRBASE_JSON_FORMAT=wt_flat",
"ctodeakai/openehr-mcp-server:latest"
]
}
}
}
You can point EHRBASE_URL to your own EHRbase server or use the provided docker-compose setup.
The MCP server supports different JSON serialization formats for interacting with the EHRbase API. You can configure the format using the optional EHRBASE_JSON_FORMAT environment variable:
"-e", "EHRBASE_JSON_FORMAT=wt_flat"
Available format options:
wt_flat (default): Use the simplified data types (SDT) based on the flat web template format
canonical: Uses the canonical openEHR JSON format consistently across all operations
wt_structured: SDT based on the structured web template format (currently not working)
For more information on how to set up Claude Desktop with MCP servers, see https://modelcontextprotocol.io/quickstart/user.
1. Navigate to the docker-compose directory:
cd docker-compose
2. Start the EHRbase server in detached mode:
docker compose up -d
3. Check the logs to verify the server is running properly:
docker compose logs -f
4. The EHRbase server will be available at http://localhost:8080/ehrbase/
5. The EHRBase API documentation should be here: http://localhost:8080/ehrbase/swagger-ui/index.html
To run the tests, you'll need to install the test dependencies first:
pip install -r requirements-test.txt
After installing the test dependencies and uploading the template, you can run the tests with:
python -m pytest tests/test_.py -v
This will run all the tests in the tests directory.
docker run -i --rm --network=host openehr-mcp-server
openehr_template_list: List all available openEHR templates from the EHRbase server
openehr_template_get: Retrieve a specific openEHR template by its unique identifier
openehr_template_example_composition: Generate an example openEHR composition based on a specific template
openehr_ehr_create: Create a new EHR in the system
openehr_ehr_get: Retrieve an EHR by its ID
openehr_ehr_list: List all available EHRs in the system
openehr_ehr_get_by_subject: Get an EHR by subject ID and namespace
openehr_composition_create: Create a new openEHR composition in the Electronic Health Record
openehr_composition_get: Retrieve an existing openEHR composition by its unique identifier
openehr_composition_update: Update an existing openEHR composition in the Electronic Health Record
openehr_composition_delete: Delete an existing openEHR composition from the Electronic Health Record
openehr_query_adhoc: Execute an ad-hoc AQL query against the openEHR server
Claude Desktop / Cursor
Paste into your MCP client config file to install this server.
{
"mcpServers": {
"openehr mcp server": {
"openehr-mcp-server": {
"command": "docker",
"args": [
"compose",
"up",
"-d"
]
}
}
}
}McpServers
{
"openehr-mcp-server": {
"command": "docker",
"args": [
"compose",
"up",
"-d"
]
}
}An MCP (Model Context Protocol) server designed to interface with openEHR REST APIs, specifically the EHRbase implementation.
This server enables MCP clients like Claude Desktop to create compositions for openEHR templates and submit them to a server.
For production grade EHR integrations you must use an AI Model where you can ensure data privacy.
See https://modelcontextprotocol.io/introduction for more information about MCP.
Version
Current version: 0.1.0
This project follows semantic versioning. For details on our versioning strategy, see VERSIONING.md.
MCP Tools
openehr_template_list: List all available openEHR templates from the EHRbase server
openehr_template_get: Retrieve a specific openEHR template by its unique identifier
openehr_template_example_composition: Generate an example openEHR composition based on a specific template
openehr_ehr_create: Create a new EHR in the system
openehr_ehr_get: Retrieve an EHR by its ID
openehr_ehr_list: List all available EHRs in the system
openehr_ehr_get_by_subject: Get an EHR by subject ID and namespace
openehr_composition_create: Create a new openEHR composition in the Electronic Health Record
openehr_composition_get: Retrieve an existing openEHR composition by its unique identifier
openehr_composition_update: Update an existing openEHR composition in the Electronic Health Record
openehr_composition_delete: Delete an existing openEHR composition from the Electronic Health Record
openehr_query_adhoc: Execute an ad-hoc AQL query against the openEHR server
MCP Prompts
- vital_signs_capture: Capture vital signs for a specific EHR ID
MCP Resource
Not yet implemented
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
