The openEHR MCP Server acts as a bridge between MCP clients (such as Claude Desktop, Cursor, or LibreChat) and an openEHR REST endpoint. It exposes MCP tools for managing openEHR templates, EHRs, compositions, stored queries, and AQL execution, following the openEHR REST specifications. Use the server to perform common operations like listing or retrieving templates, creating and querying EHRs and compositions, and running AQL queries. Optional guided prompts help orchestrate multi-step workflows such as vital signs capture, patient assessments, and medication reviews, guiding AI assistants through template selection, example fetches, and composition creation. Transport options include a streamable HTTP interface via Caddy or a stdio-based workflow for process-based clients.

Prerequisites:

• Docker and Docker Compose installed on the host
• Git
• (Optional) Make installed for convenience

Install and run locally (production/docker-based):

1. Clone the repository: git clone https://github.com/cadasto/openehr-server-mcp.git cd openehr-server-mcp

2. Prepare environment (copies and defaults can be edited in .env): make env

   Or edit .env directly to set OPENEHR_API_BASE_URL and related vars

3. Start the MCP server (production via Docker): make up

   Caddy serves HTTP/HTTPS; dev setup may expose additional ports

4. (Optional) Start EHRbase stack for testing: make ehrbase-up

   EHRbase will be available at http://localhost:8080

Development/contributor workflow (local/docker-based):

1. Clone and enter the repo as above.
2. Prepare environment (same as step 2 above).
3. Start in development mode: make up-dev

   Uses a development compose with developer tooling

Notes:

• Ensure OPENEHR_API_BASE_URL in the environment points to your openEHR REST endpoint.
• For local testing, you can run EHRbase locally and point OPENEHR_API_BASE_URL to that instance.
• If you modify code, use the development workflow to test changes before production deployment.

Tips and caveats:

• OAuth2 flows are not supported yet; this server is intended for development and testing.
• Transport options include streamable HTTP (via Caddy) and stdio; use the transport appropriate for your MCP client.
• Environment-driven configuration is supported; you can set OPENEHR_API_BASE_URL and other variables via the provided .env file.
• The repository uses PHP 8.4; the server is PHP-based with PSR-compliant code and Monolog for logging.
• If you run the Docker-based setup, ensure external access to the openEHR REST endpoint is properly secured and compliant with your data governance policies.