Used for managing environment variables that store Medplum server connection details and authentication credentials.
Provides linting for the MCP server codebase to ensure code quality.
Used for integration testing against a live Medplum instance to verify FHIR resource operations.
Serves as the runtime environment for the MCP server that interfaces with Medplum.
Used during development to automatically restart the server on code changes.
Used for package management and running scripts within the MCP server project.
Integrated with the test harness to process natural language queries into FHIR operations on the Medplum server.
Handles code formatting for the MCP server codebase.
Used as the implementation language for the MCP server's tools and configurations.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Medplum MCP Server search for patients named John Smith"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
This project implements a complete Model Context Protocol (MCP) server designed to seamlessly interact with a Medplum FHIR server. The MCP server provides a standardized interface, enabling Large Language Models (LLMs) to perform Create, Read, Update, and Search (CRUDS) operations on various FHIR resources through a comprehensive suite of tools. This empowers users to manage healthcare data stored in Medplum using natural language commands through any MCP-compatible client (Claude Desktop, VS Code MCP extensions, etc.).
The server implements the full MCP protocol specification, providing 33 comprehensive FHIR resource management tools that can be discovered and executed by any MCP client. Users can intuitively manage patient information, practitioners, organizations, encounters, observations, and more by conversing with an LLM that leverages the MCP tools to execute requests against the FHIR server.
Related MCP server: Medplum MCP Server
🎉 MCP Server Implementation Complete! 🎉
What's Implemented:
✅ Core FHIR resource management tools (Patient, Practitioner, Organization, Encounter, Observation, Medication, etc.)
✅ MCP Server Protocol Implementation - Full Model Context Protocol server with stdio transport
✅ Comprehensive tool schemas for LLM interaction (33 FHIR tools)
✅ Interactive Chat Harness - Full MCP client with natural language interface
✅ Jest integration tests for all tools
✅ Medplum FHIR server connectivity and authentication
✅ MCP Inspector testing and validation
✅ Claude Desktop integration configuration
Ready for Use:
🔄 The MCP server is fully functional and ready for integration with MCP clients
✅ All 33 FHIR tools are properly registered and working
🔄 Server successfully authenticates with Medplum and executes FHIR operations
🔄 Interactive chat harness available - Test all tools with natural language
🔄 Tested with MCP Inspector - all tools discoverable and executable
🔄 Claude Desktop configuration provided for immediate use
Current Capabilities:
Full CRUD operations on FHIR resources through natural language
Interactive chat interface for testing and development
Seamless integration with any MCP-compatible client (Claude Desktop, VS Code MCP extensions, etc.)
Comprehensive error handling and logging
Production-ready MCP protocol implementation
The MCP server currently supports a comprehensive set of 33 tools for managing various FHIR resources:
src/tools/patientUtils.tscreatePatient: Create new patient records with demographics, identifiers, and contact information.
getPatientById: Retrieve complete patient details by their unique ID.
updatePatient: Modify existing patient information including demographics and contact details.
searchPatients: Find patients based on name, birthdate, identifier, or other criteria.
src/tools/practitionerUtils.tscreatePractitioner: Register new healthcare practitioners with their professional details.
getPractitionerById: Fetch complete practitioner details by their unique ID.
updatePractitioner: Update practitioner information including qualifications and contact details.
searchPractitionersByName: Search for practitioners using their first or last name.
searchPractitioners: Conduct advanced searches for practitioners based on multiple criteria.
src/tools/organizationUtils.tscreateOrganization: Add new healthcare organizations (hospitals, clinics, departments).
getOrganizationById: Retrieve complete organization details by their unique ID.
updateOrganization: Update organization information including contact details and addresses.
searchOrganizations: Search for organizations by name, type, or other attributes.
src/tools/encounterUtils.tscreateEncounter: Create new patient encounters (visits, appointments, hospital stays).
getEncounterById: Retrieve complete encounter details by their unique ID.
updateEncounter: Update encounter information including status, class, and participants.
searchEncounters: Search for encounters by patient, practitioner, date, status, or class.
src/tools/observationUtils.tscreateObservation: Record new observations (lab results, vital signs, diagnostic findings).
getObservationById: Retrieve complete observation details by their unique ID.
updateObservation: Modify existing observations including values, status, and interpretations.
searchObservations: Search for observations by patient, code, date, or encounter.
src/tools/medicationRequestUtils.tscreateMedicationRequest: Create new medication requests (prescriptions) with dosage and instructions.
getMedicationRequestById: Retrieve complete medication request details by their unique ID.
updateMedicationRequest: Update prescription information including status, dosage, and instructions.
searchMedicationRequests: Search for medication requests by patient, medication, or prescriber.
src/tools/medicationUtils.tscreateMedication: Create new medication resources with codes, names, and formulations.
getMedicationById: Retrieve complete medication details by their unique ID.
searchMedications: Search for medications by code, name, or ingredient.
src/tools/episodeOfCareUtils.tscreateEpisodeOfCare: Create new episodes of care for managing patient care over time.
getEpisodeOfCareById: Retrieve complete episode of care details by their unique ID.
updateEpisodeOfCare: Update episode information including status, period, and managing organization.
searchEpisodesOfCare: Search for episodes of care by patient, status, or managing organization.
generalFhirSearch: Generic FHIR search with custom parameters for any resource type, enabling advanced queries across all FHIR resources.
Each tool is exposed to the LLM via a well-defined JSON schema and is callable through a dedicated test harness (src/llm-test-harness.ts), facilitating robust testing and integration.
Runtime: Node.js
Language: TypeScript
FHIR Server Interaction: @medplum/core, @medplum/fhirtypes
LLM Integration: OpenAI API (specifically gpt-4o in the test harness)
Testing: Jest (for integration tests), Manual E2E via test harness
Linting & Formatting: ESLint, Prettier
Environment Management: dotenv
HTTP Client (for Medplum SDK): node-fetch
medplum-mcp/
├── src/ # Source code
│ ├── config/ # Medplum client configuration (medplumClient.ts)
│ ├── tools/ # FHIR resource utility functions (patientUtils.ts, etc.)
│ ├── lib/ # Shared libraries (currently unused)
│ ├── index.ts # Main application entry point
│ ├── llm-test-harness.ts # Script for testing LLM tool calling
│ └── test-connection.ts # Script for basic Medplum connection test
├── tests/ # Test suites
│ └── integration/ # Jest integration tests for tools
├── .eslintrc.js
├── .gitignore
├── .prettierrc.js
├── .prettierignore
├── package.json
├── tsconfig.json
└── README.mdPrerequisites:
Node.js (refer to package.json for engine specifics; LTS versions recommended)
A running Medplum server instance (e.g., local Dockerized instance at http://localhost:8103/)
Medplum client credentials (Client ID and Client Secret)
Installation:
git clone https://github.com/rkirkendall/medplum-mcp.git
cd medplum-mcp
npm installEnvironment Variables:
Create a .env file in the project root with your specific Medplum server details and API keys:
MEDPLUM_BASE_URL=http://your-medplum-server-url/
MEDPLUM_CLIENT_ID=your_client_id
MEDPLUM_CLIENT_SECRET=your_client_secret
OPENAI_API_KEY=your_openai_api_key # Required for llm-test-harness.tsThe most user-friendly way to test your MCP server is through the interactive chat interface:
# Build and run the chat harness
npm run chat
# Or in development mode
npx ts-node src/llm-test-harness.tsFeatures:
🗣️ Natural language interaction with all 33 FHIR tools
🔧 Automatic tool discovery and execution
📋 Built-in help and examples
🔄 Conversation context maintenance
⚡ Real-time tool execution and results
Example Session:
🏥 You: Create a new patient Jane Smith born 1985-03-20
🤖 Assistant: I'll create a new patient record for Jane Smith...
🏥 You: Find all doctors named Stevens
🤖 Assistant: I found 2 practitioners with the name Stevens...See CHAT_HARNESS_USAGE.md for detailed usage instructions and IMPLEMENTATION_PLAN.md for development details.
npm start # Runs the MCP server with stdio transport
npm run dev # Development mode with live reloading# MCP Inspector (web-based tool testing)
npx @modelcontextprotocol/inspector node dist/index.js
# Legacy OpenAI integration (deprecated)
npm run test:harnessIntegration tests use Jest and interact with a live Medplum instance (configured via .env).
To run all integration tests:
npx jest tests/integrationTo run specific integration test files:
npx jest tests/integration/patient.integration.test.ts
npx jest tests/integration/practitioner.integration.test.ts
npx jest tests/integration/organization.integration.test.ts
# Add other specific test files as neededThis project is licensed under the MIT License - see the LICENSE file for details.
Creates a new condition or diagnosis for a patient. Requires a patient ID and a condition code.
Inputs: code (required), patientId (required), clinicalStatus, onsetString, +1 more.
Creates a new encounter (patient visit). Requires patient ID and status.
Inputs: classCode (required), patientId (required), status (required), organizationId, +1 more.
Creates a new episode of care for a patient. Requires patient ID and status.
Inputs: patientId (required), status (required), managingOrganizationId.
Creates a new medication resource. Requires medication code or identifier.
Inputs: code (required), display, form.
Creates a new medication request (prescription). Requires patient ID, medication reference, and prescriber.
Inputs: intent (required), medicationReference (required), patientId (required), practitionerId (required), +1 more.
Creates a new observation (lab result, vital sign, etc.). Requires patient ID and code.
Inputs: code (required), patientId (required), status (required), encounterId, +2 more.
Creates a new organization (e.g., hospital, clinic). Requires organization name.
Inputs: name (required), alias.
Creates a new patient resource. Requires first name, last name, and birth date.
Inputs: birthDate (required), firstName (required), lastName (required), gender.
Creates a new medical practitioner. Requires given name and family name.
Inputs: familyName (required), givenName (required).
Performs a generic FHIR search operation on any resource type with custom query parameters.
Inputs: queryParams (required), resourceType (required).
Retrieves a condition resource by its unique ID.
Inputs: conditionId (required).
Retrieves an encounter by its unique ID.
Inputs: encounterId (required).
Retrieves an episode of care by its unique ID.
Inputs: episodeOfCareId (required).
Retrieves a medication by its unique ID.
Inputs: medicationId (required).
Retrieves a medication request by its unique ID.
Inputs: medicationRequestId (required).
Retrieves an observation by its unique ID.
Inputs: observationId (required).
Retrieves an organization by its unique ID.
Inputs: organizationId (required).
Retrieves a patient resource by their unique ID.
Inputs: patientId (required).
Retrieves a practitioner resource by their unique ID.
Inputs: practitionerId (required).
Searches for conditions based on patient and other criteria. Requires a patient ID.
Inputs: patientId (required), category, clinical-status, code.
Searches for encounters based on criteria like patient ID or status.
Inputs: patientId, practitionerId, status.
Searches for episodes of care based on criteria like patient ID or status.
Inputs: managingOrganizationId, patientId, status.
Searches for medication requests based on criteria like patient ID or medication.
Inputs: medicationReference, patientId, practitionerId, status.
Searches for medications based on criteria like code or name.
Inputs: code, form, name.
Searches for observations based on criteria like patient ID or code.
Inputs: code, encounterId, patientId, status.
Searches for organizations based on criteria like name or address. Provide at least one criterion.
Inputs: address, name.
Searches for patients based on criteria like name or birth date.
Inputs: birthdate, family, gender, given.
Searches for practitioners based on various criteria like name, specialty, or identifier.
Inputs: family, given, identifier, name, +1 more.
Searches for medical practitioners based on their given name, family name, or a general name string.
Inputs: familyName, givenName, name.
Updates an existing condition. Requires the condition ID and at least one field to update.
Inputs: conditionId (required), clinicalStatus, onsetString, verificationStatus.
Updates an existing encounter. Requires the encounter ID and the fields to update.
Inputs: encounterId (required), status.
Updates an existing episode of care. Requires the episode ID and fields to update.
Inputs: episodeOfCareId (required), status.
Updates an existing medication request. Requires the medication request ID and fields to update.
Inputs: medicationRequestId (required), status.
Updates an existing observation. Requires the observation ID and the fields to update.
Inputs: observationId (required), status, valueQuantity, valueString.
Updates an existing organization. Requires the organization ID and the fields to update.
Inputs: organizationId (required), alias, name.
Updates an existing patient's information. Requires the patient's ID and the fields to update.
Inputs: patientId (required), birthDate, firstName, gender, +1 more.
Updates an existing practitioner's information. Requires the practitioner's ID and the fields to update.
Inputs: practitionerId (required), active.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 37 tools
Every tool has a clearly distinct purpose with no ambiguity. Each tool targets a specific FHIR resource type (e.g., Patient, Condition, Observation) combined with a specific operation (create, get, search, update), making it easy for an agent to select the correct tool. The descriptions reinforce this clarity by specifying required parameters and use cases.
Tool names follow a highly consistent verb_noun pattern throughout, such as createPatient, getPatientById, searchPatients, updatePatient. This pattern is applied uniformly across all 37 tools, with no deviations in style or convention, making the set predictable and easy to navigate.
With 37 tools, the count feels heavy for a typical MCP server, bordering on excessive. While the tools cover multiple FHIR resources comprehensively, such a large number might overwhelm agents or lead to inefficiencies in tool selection, despite the clear organization. A more streamlined set could improve usability without sacrificing functionality.
The tool surface is complete for the FHIR domain, offering full CRUD/lifecycle coverage (create, get, search, update) for key resources like Patient, Condition, Observation, and others. There are no obvious gaps; agents can perform all essential operations without dead ends, supported by the generalFhirSearch tool for custom queries.
Securely access and manage FHIR healthcare data stored in Medplum.
Hosted MCP server for AI-driven data ops. Create apps, manage schemas, and CRUD structured data.
Hosted MCP server exposing US hospital procedure cost data to AI assistants
An MCP server that provides an API to LLMs to manage their JumpCloud resources.
