medplum

This Medplum MCP Server acts as a proxy that connects MCP clients to Medplum's FHIR data. It accepts MCP requests, forwards them to Medplum via the configured base URL, and returns enriched context to language models or tools that consume MCP streams. You can test and explore the MCP endpoints using the included inspector tool and by pointing your MCP client to the server's /stream and /sse endpoints.

To start using it, first configure the Medplum base URL in a .env file (MEDPLUM_BASE_URL) and optionally set the listening port (PORT). After building, run the production server and then connect your MCP client (or the MCP Inspector) to the appropriate endpoints. The server exposes a streaming endpoint at /stream and a Server-Sent Events endpoint at /sse for standard MCP data flows.

Prerequisites:

• Node.js (LTS) and npm installed
• Access to a Medplum instance or public Medplum API (MEDPLUM_BASE_URL)

1. Clone the repository git clone <repository-url> cd medplum-medplum-mcp-server

2. Install dependencies npm install

3. Create a .env file with required configuration MEDPLUM_BASE_URL=https://api.medplum.com/ PORT=8104 # optional, defaults to 8104

4. Build the production server npm run build

5. Run the production server nohup node --max-old-space-size=8192 dist/main.cjs &

6. Optional: Run in development mode npm run dev

7. Verify the server is running by hitting the endpoints (e.g., http://localhost:8104/stream and http://localhost:8104/sse).

Environment and configuration tips:

• MEDPLUM_BASE_URL must point to a valid Medplum API endpoint (including port if self-hosted).
• If Medplum requires authentication, you may need to handle API keys or OAuth tokens in your environment or client requests depending on your Medplum setup.
• The server defaults to port 8104; change PORT in .env to run on a different port.
• For production use, ensure your process is managed (e.g., systemd, PM2) since the example uses nohup for long-running processes.
• Use MCP Inspector to test streaming (/stream) and SSE (/sse) endpoints and verify correct MCP payloads.
• If you encounter CORS issues in browser clients, consider enabling appropriate CORS handling in the server or via a proxy.
• Monitor memory usage; the production command allocates up to 8 GB heap space with --max-old-space-size=8192.