FHIR MCP Server
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., "@FHIR MCP Server search for patients with type 2 diabetes and list their recent HbA1c results"
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.
π Table of Contents
Related MCP server: LangCare MCP FHIR Server
π About The Project
FHIR MCP Server implements a complete Model Context Protocol (MCP) server, designed to facilitate seamless interaction between LLM-based agents and a FHIR-compliant backend. It provides a standardized interface that enables full CRUD operations on FHIR resources through a comprehensive suite of tools - accessible from MCP-compatible clients such as Claude Desktop, allowing users to query and manipulate clinical data using natural-language prompts.
β¨ Key Features
π FastMCP Framework: Built on FastMCP for high-performance MCP server capabilities
π₯ FHIR Resource Management: Full CRUD operations for all major FHIR resources
π Intelligent Document Processing: AI-powered document ingestion and chunking for multiple formats including TXT, CSV, JSON, and PDF
π Semantic Search: Advanced document search using vector embeddings (via Pinecone)
π§ RAG-Ready: Retrieval-Augmented Generation pipeline with context-aware document queries
π Secure Authentication: OAuth2 token management for FHIR API integration
π LOINC Integration: Standardized medical terminology lookup and validation
π³ Container Ready: Docker support for easy deployment and scaling
π§ Configurable: Extensive
.env-based configuration options
ποΈ Architecture
The server is built with a modular architecture:
MCP Tools: Dedicated tools for selected FHIR resource types, with others handled by a generic tool
Fhir Server Client: Handles FHIR API communication and authentication (OAuth2 and more planned)
RAG Services: Embedding-based document processing and semantic retrieval
Vector Store: Pinecone integration for similarity-based search
LOINC Client: Integration with LOINC API for terminology resolution and validation
π‘ Demo
This demo shows how Claude uses the fhir-mcp-server to communicate with a FHIR server (in this case Medplum) to answer questions. You will see, among other things:
utilization of the
request_patient_resourcetool which retrieves basic patient informationutilization of the
request_condition_resourcetool to answer the question whether any of the previously diagnosed diseases may cause symptoms that the patient is currently complaining aboututilization of the
request_medication_resource,request_encounter_resource,request_generic_resourcetools to answer the question whether the patient has already received any treatment for hypertension
You can observe how Claude automatically selects the tools worth using to answer the question based on the user's query.
https://github.com/user-attachments/assets/3a3a8ed3-f881-447d-af03-5f24432a2cdd
Here you can observe how Claude first uses the tool searching for LOINC codes for the lipid panel specific codes, but not finding any related observations in FHIR server, it repeats the search for individual biomarkers that make up such a panel.
https://github.com/user-attachments/assets/2fb39801-d5d6-4461-bedd-9f58ab4d52ec
Developers working with FHIR often need to generate specific test data to validate FHIR server functionality, such as search capabilities and data relationships. While you can use Synthea to generate synthetic data and then manually import the resulting bundles to your server, fhir-mcp-server streamlines this process by allowing you to generate and deploy test data directly through Claude.
This eliminates the typical workflow of running synthea separately, downloading bundles, and manually importing them to your FHIR server. Instead, you can create targeted test scenarios, generate appropriate synthetic data, and populate your server all within Claude's interface.
https://github.com/user-attachments/assets/d87da1d8-6401-4a9e-a6f0-50ba23396e12
Note: fhir-mcp-server was not designed with this use case in mind, so as you'll see in the demo, it doesn't work perfectly - what can be observed, however, is how well the LLM handles using trial and error to correct any wrong choices.
π Getting Started
Follow these steps to set up FHIR MCP Server in your environment.
Prerequisites
Docker (recommended) or uv: For dependency management
FHIR Server Account: Access to FHIR API (e.g. Medplum)
Pinecone API key (required for document search): Enables vector-based search over processed documents. Without it, semantic retrieval features will be unavailable.
LOINC Account (optional): Enables retrieval of the latest LOINC codes from the official API. Without it, the system relies on static or language model-inferred codes, which may be outdated or imprecise.
Installation & Setup
Clone the repository:
git clone https://github.com/the-momentum/fhir-mcp-server cd fhir-mcp-serverSet up environment variables:
cp config/.env.example config/.envEdit the
config/.envfile with your credentials and configuration. See Environment VariablesInstall Dependencies
For Docker-based execution run:
make buildFor uv-based execution run:
make uvUpdate the MCP Client configuration
e.g. Claude Desktop -> edit
claude_desktop_config.json
Docker
{ "mcpServers": { "docker-mcp-server": { "command": "docker", "args": [ "run", "-i", "--rm", "--init", "--name", "fhir-mcp-server", "--mount", // optional - volume for reload "type=bind,source=<your-project-path>/app,target=/root_project/app", // optional - volume for reload "--mount", "type=bind,source=<your-project-path>/config/.env,target=/root_project/config/.env", "-e", "TRANSPORT_MODE=stdio", // Set transport mode: stdio, http, or https "mcp-server:latest" ] } } }Make sure to replace
<your-project-path>with the actual path to your installationuv
Firstly, get uv path from terminal:
Windows:
(Get-Command uv).PathMacOS/Linux:
which uv
Then, update config file:
{ "mcpServers": { "uv-mcp-server": { "command": "uv", "args": [ "run", "--frozen", "--directory", "<your-project-path>", "start" ], "env": { "PATH": "<uv-bin-folder-path>" } } } }Make sure to replace with the actual uv path (to bin folder)
Restart MCP Client
After completing all of the above steps, restart the MCP Client to apply the changes. In some cases, you may need to terminate all related processes using Task Manager or your system's process manager. This ensures that:
The updated configuration is properly loaded
Environment variables are correctly applied
The FHIR MCP client initializes with the correct settings
π§ Configuration
π Security & Encryption
The FHIR MCP Server includes built-in encryption infrastructure to protect sensitive configuration values. Sensitive fields like API keys and passwords are automatically encrypted and decrypted at runtime.
You are allowed to store passwords as a plain text, but if you want to have them encrypted, follow the instruction below.
Setting Up Encryption
For most users, use the automated setup script:
# uv method
uv run scripts/cryptography/setup_encryption.py
# docker method
docker exec fhir-mcp-server uv run scripts/cryptography/setup_encryption.pyThis script will:
Check for
MASTER_KEYinconfig/.envand generate one if neededAutomatically encrypt all sensitive values (
LOINC_PASSWORD,FHIR_SERVER_CLIENT_SECRET,PINECONE_API_KEY)Update your
.envfile with encrypted valuesSkip empty variables and already encrypted values
Generate a Master Key:
# uv method uv run scripts/cryptography/generate_master_key.py # docker method docker exec fhir-mcp-server uv run scripts/cryptography/generate_master_key.pyPut that key as a MASTER_KEY environment variable in .env.
Encrypt Sensitive Values:
# uv method uv run scripts/cryptography/encrypt_setting.py "your_secret_value" # docker method docker exec fhir-mcp-server uv run scripts/cryptography/encrypt_setting.py "your_secret_value"Decrypt Values (for verification):
# uv method uv run scripts/cryptography/decrypt_setting.py "encrypted_value" # docker method docker exec fhir-mcp-server uv run scripts/cryptography/decrypt_setting.py "encrypted_value"
Encrypted Configuration Fields
The following fields are automatically encrypted when using EncryptedField:
FHIR_SERVER_CLIENT_SECRET- OAuth2 client secret for FHIR serverLOINC_PASSWORD- LOINC account passwordPINECONE_API_KEY- Pinecone API key for vector search
Environment Variables
Variable | Description | Example Value | Encryption |
MASTER_KEY | Master encryption key |
| Required |
FHIR_SERVER_HOST | FHIR API host URL |
| No |
FHIR_BASE_URL | FHIR base path |
| No |
FHIR_SERVER_CLIENT_ID | OAuth2 client ID for FHIR |
| No |
FHIR_SERVER_CLIENT_SECRET | OAuth2 client secret for FHIR |
| Yes |
LOINC_ENDPOINT | LOINC API search endpoint |
| No |
LOINC_USERNAME | LOINC account username |
| No |
LOINC_PASSWORD | LOINC account password |
| Yes |
PINECONE_API_KEY | Pinecone API key |
| Yes |
EMBEDDING_MODEL | Hugging Face embedding model name |
| No |
π οΈ MCP Tools
The FHIR MCP Server provides a comprehensive set of tools for interacting with FHIR resources and document management:
FHIR Resource Tools
Tool | Resource Type | Description |
| Patient | Manage patient demographic and administrative information |
| Observation | Handle clinical measurements and assessments |
| Condition | Manage patient problems and diagnoses |
| Medication | Handle medication information and orders |
| Immunization | Manage vaccination records |
| Encounter | Handle patient visits and interactions |
| AllergyIntolerance | Manage patient allergy information |
| FamilyMemberHistory | Handle family health history |
| Any FHIR Resource | Operate on any FHIR resource not covered by specific tools |
Document Management Tools
Tool | Description |
| Manage FHIR DocumentReference resources |
| Ingests documents into the vector database for semantic search |
| Performs semantic search across indexed documents using vector embeddings |
LOINC Terminology Tools
Tool | Description |
| Retrieves standardized LOINC codes for medical observations and laboratory tests |
Tool Features
Full Resource Management: All FHIR resource tools support Create, Read, Update, and Delete operations
Data Validation: Tools enforce FHIR resource validation and prevent data corruption
Error Handling: Comprehensive error responses with detailed failure information
Security: OAuth2 authentication and proper access control for all operations
Semantic Search: AI-powered document search using vector embeddings
Multi-format Support: Document ingestion supports TXT, PDF, CSV, and JSON formats
πΊοΈ Roadmap
We're continuously enhancing FHIR MCP Server with new capabilities. Here's what's on the horizon:
Extended Authentication Options: In addition to OAuth2 (already supported), we plan to add support for other authentication methods for connecting to FHIR servers
Expanded File Format Support for RAG: Extend document ingestion capabilities to support additional formats
Table-Aware Document Chunking: Improve the document chunking pipeline by detecting tables in documents and treating them as separate, atomic chunks.
OCR Support for Scanned Documents: Implement Optical Character Recognition capabilities to enable extraction of text from scanned PDFs and image files before chunking and indexing
Have a suggestion? We'd love to hear from you! Contact us or contribute directly.
π₯ Contributors
π License
Distributed under the MIT License. See MIT License for more information.
Available Tools
13 toolsadd_document_to_pineconeB
IMPORTANT: Always inform the user at the beginning of your response that this search operation may take some time because the embedding model will be loaded into cache. Adds a document to the Pinecone vector index for the specified FHIR DocumentReference ID.
This tool should be used to ingest new documents into the Pinecone index.
Rules: - If you cannot determine the format of the document fitting the format from the list, provide the format as None. - After adding the document, the Pinecone index may take up to 1 minute to update before the document is searchable.
Args: url (str): The URL of the document to be added. fhir_document_id (str): The ID of the FHIR DocumentReference resource corresponding to the document. format (literal | None): The format of the document.
Returns: str: Confirmation message that the document was added or already exists. PineconeError: Error object with a message if the operation fails.
Inputs: document (required). Returns: result
get_loinc_codesA
Get the most relevant LOINC codes for a given observation name.
The function automatically:
Filters for STATUS="ACTIVE" codes only
Sorts by COMMON_TEST_RANK (lower rank = more commonly used)
Returns codes in popularity order (most common first)
Your job is to:
Analyze returned codes for semantic relevance to the search query
Balance clinical popularity with semantic matching
Select codes that best match the intended observation
Strategy:
Start with default parameters (max_codes=5, max_fetch=50)
Check if result contains "Error" key in first element
If "Authentication failed" or "Authorization" error:
STOP using this tool immediately.
Do not retry with different parameters.
Report the authentication error to the user.
Suggest they check their LOINC API credentials.
Ask the user if they want to use your knowledge to find a LOINC code and wait for the confirmation. Add warning that this may cause wrong results.
If "No active LOINC codes found in current fetch":
Increase max_fetch progressively (50β100β200βRecordsFound).
Keep trying until max_fetch >= RecordsFound or you find active codes.
If "No LOINC codes found": Try alternative search terms or report failure.
If you get codes but they don't semantically match your query:
Increase max_codes to see more options.
Look for better matches in COMPONENT, SHORTNAME, LONG_COMMON_NAME fields.
Rules:
Function returns codes sorted by popularity - YOU decide which are most relevant.
Don't automatically pick the first (most common) codes.
Prioritize semantic relevance: exact matches in COMPONENT > SHORTNAME > partial matches.
Balance popularity with relevance (very rare codes might not be clinically useful).
Keep increasing max_fetch until you exhaust all available records (max_fetch >= RecordsFound).
Increase max_codes only when you need more options to find better semantic matches.
Args: component_name: The name of the observation to get the LOINC code for (i.e. "glucose"). max_codes: The maximum number of LOINC codes to return. max_fetch: The maximum number of LOINC codes to fetch from the API. Returns: LOINC codes sorted by popularity - you must select the most semantically relevant ones.
Inputs: component_name (required), max_codes, max_fetch. Returns: result
request_allergy_intolerance_resourceA
Makes an HTTP request to the FHIR server. Use this tool to perform CRUD operations only on the FHIR AllergyIntolerance resource. Rules: - When creating or updating an allergy intolerance, use only the data explicitly provided by the user. - Do not guess, auto-fill, or assume any missing data. - When deleting an allergy intolerance, ask the user for confirmation with details of the allergy intolerance and wait for the user's confirmation. - Provide links to the app (not api) allergy intolerance resource in the final response.
Args: method: HTTP method (GET, POST, PUT, DELETE) path: Resource path (e.g., "/AllergyIntolerance", "/AllergyIntolerance?patient=Patient/123") body: Optional JSON data for POST/PUT requests)
Returns: JSON response from the FHIR server
Inputs: request (required). Returns: result
request_condition_resourceA
Makes an HTTP request to the FHIR server. Use this tool to perform CRUD operations only on the FHIR Condition resource. Rules: - When creating or updating a condition, use only the data explicitly provided by the user. - Do not guess, auto-fill, or assume any missing data. - When deleting a condition, ask the user for confirmation with details of the condition and wait for the user's confirmation. - Provide links to the app (not api) condition resource in the final response.
Args: method: HTTP method (GET, POST, PUT, DELETE) path: Resource path (e.g., "/Condition", "/Condition?patient=Patient/123") body: Optional JSON data for POST/PUT requests)
Returns: JSON response from the FHIR server
Inputs: request (required). Returns: result
request_document_reference_resourceA
Makes an HTTP request to the FHIR server. Use this tool to perform CRUD operations only on the FHIR DocumentReference resource. Rules: - When creating or updating a document reference, use only the data explicitly provided by the user. - Do not guess, auto-fill, or assume any missing data. - When deleting a document reference, ask the user for confirmation with details of the document and wait for the user's confirmation. - Provide links to the app (not api) document reference resource in the final response.
Args: method: HTTP method (GET, POST, PUT, DELETE) path: Resource path (e.g., "/DocumentReference", "/DocumentReference?patient=Patient/123") body: Optional JSON data for POST/PUT requests
Returns: JSON response from the FHIR server
Inputs: request (required). Returns: result
request_encounter_resourceA
Makes an HTTP request to the FHIR server. Use this tool to perform CRUD operations only on the FHIR Encounter resource. Rules: - When creating or updating an encounter, use only the data explicitly provided by the user. - Do not guess, auto-fill, or assume any missing data. - When deleting an encounter, ask the user for confirmation with details of the encounter and wait for the user's confirmation. - Provide links to the app (not api) encounter resource in the final response.
Args: method: HTTP method (GET, POST, PUT, DELETE) path: Resource path (e.g., "/Encounter", "/Encounter?patient=Patient/123") body: Optional JSON data for POST/PUT requests)
Returns: JSON response from the FHIR server
Inputs: request (required). Returns: result
request_family_member_history_resourceA
Makes an HTTP request to the FHIR server. Use this tool to perform CRUD operations only on the FHIR FamilyMemberHistory resource. Rules: - When creating or updating a family member history, use only the data explicitly provided by the user. - Do not guess, auto-fill, or assume any missing data. - When deleting a family member history, ask the user for confirmation with details of the family member history and wait for the user's confirmation. - Provide links to the app (not api) family member history resource in the final response.
Args: method: HTTP method (GET, POST, PUT, DELETE) path: Resource path (e.g., "/FamilyMemberHistory", "/FamilyMemberHistory?patient=Patient/123") body: Optional JSON data for POST/PUT requests)
Returns: JSON response from the FHIR server
Inputs: request (required). Returns: result
request_generic_resourceA
Makes an HTTP request to the FHIR server. Use this tool to perform CRUD operations on any FHIR resource ONLY if the other tools are not applicable.
Rules: - When creating or updating a resource, use only the data explicitly provided by the user. - Do not guess, auto-fill, or assume any missing data. - When deleting a resource, ask the user for confirmation with details of the resource and wait for the user's confirmation. - Provide links to the app (not api) resource in the final response.
Args: method: HTTP method (GET, POST, PUT, DELETE) path: Resource path body: Optional JSON data for POST/PUT requests)
Returns: JSON response from the FHIR server
Inputs: request (required). Returns: result
request_immunization_resourceA
Makes an HTTP request to the FHIR server. Use this tool to perform CRUD operations only on the FHIR Immunization resource. Rules: - When creating or updating an immunization, use only the data explicitly provided by the user. - Do not guess, auto-fill, or assume any missing data. - When deleting an immunization, ask the user for confirmation with details of the immunization and wait for the user's confirmation. - Provide links to the app (not api) immunization resource in the final response.
Args: method: HTTP method (GET, POST, PUT, DELETE) path: Resource path (e.g., "/Immunization", "/Immunization?patient=Patient/123") body: Optional JSON data for POST/PUT requests)
Returns: JSON response from the FHIR server
Inputs: request (required). Returns: result
request_medication_resourceA
Makes an HTTP request to the FHIR server. Use this tool to perform CRUD operations only on the FHIR Medication resource. Rules: - When creating or updating a medication, use only the data explicitly provided by the user. - Do not guess, auto-fill, or assume any missing data. - When deleting a medication, ask the user for confirmation with details of the medication and wait for the user's confirmation. - Provide links to the app (not api) medication resource in the final response.
Args: method: HTTP method (GET, POST, PUT, DELETE) path: Resource path (e.g., "/Medication", "/Medication?code=aspirin") body: Optional JSON data for POST/PUT requests)
Returns: JSON response from the FHIR server
Inputs: request (required). Returns: result
request_observation_resourceA
Makes an HTTP request to the FHIR server. Use this tool to perform CRUD operations only on the FHIR Observation resource. Rules: - When creating or updating an observation, use only the data explicitly provided by the user. - Do not guess, auto-fill, or assume any missing data. - When deleting an observation, ask the user for confirmation with details of the observation and wait for the user's confirmation. - Provide links to the app (not api) observation resource in the final response.
Args: method: HTTP method (GET, POST, PUT, DELETE) path: Resource path (e.g., "/Observation", "/Observation?subject=Patient/123") body: Optional JSON data for POST/PUT requests)
Returns: JSON response from the FHIR server
Inputs: request (required). Returns: result
request_patient_resourceA
Makes an HTTP request to the FHIR server. Use this tool to perform CRUD operations only on the FHIR Patient resource. Rules: - When creating or updating a patient, use only the data explicitly provided by the user. - Do not guess, auto-fill, or assume any missing data. - When deleting a patient, ask the user for confirmation with details of the patient and wait for the user's confirmation. - Provide links to the app (not api) patient resource in the final response.
Args: method: HTTP method (GET, POST, PUT, DELETE) path: Resource path (e.g., "/Patient", "/Patient?name=John%20Doe") body: Optional JSON data for POST/PUT requests)
Returns: JSON response from the FHIR server
Inputs: request (required). Returns: result
search_pineconeA
IMPORTANT: Always inform the user at the beginning of your response that this search operation may take some time because the embedding model will be loaded into cache. Searches the Pinecone vector index for information related to the given document by FHIR DocumentReference ID.
Use this tool when the user requests information from the documents, notes, etc.
Rules: - Firstly, prepare fhir_document_id by running the appropriate tool. - If the error message "Document does not exist in Pinecone index" is returned, automatically trigger the 'add_document_to_pinecone' tool to add the missing document to the index. - Translate the user's query into the language of the document before performing the search. - Base all answers strictly on the content found in the Pinecone index documents. - If the user's question is unrelated to the indexed documents, respond that the information is not available in the documents. - If the query is unclear or ambiguous, ask the user to clarify or provide more details. - You can modify the query to make it more specific and relevant to the document.
Args: query (str): The user's search query. fhir_document_id (str): The ID of the FHIR DocumentReference resource to search within - it is the same as the FHIR ID of the document. top_k (int, optional): The maximum number of search results to return. Defaults to 10.
Returns: list[PineconeSearchResponse]: List of search results matching the query. PineconeError: Error object with a message if the search fails.
Inputs: query (required), fhir_document_id (required), top_k. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogβ¦
TDQS
Scored across 13 tools
Each request_<resource>_resource tool targets a distinct FHIR resource type, and the Pinecone/LOINC tools have clear separate purposes. However, the many similar request_resource wrappers could lead to accidental selection of the wrong resource, and request_generic_resource may be confused with the specific ones.
The dominant request_<resource>_resource pattern is consistent, but get_loinc_codes, add_document_to_pinecone, and search_pinecone deviate with different verb styles, creating a mixed naming convention. This is readable but not fully predictable.
13 tools is well-scoped for a FHIR MCP server, covering common clinical resources plus LOINC lookup and document search. Each tool has a clear purpose and the count is neither too thin nor overwhelming.
The server covers a broad set of FHIR resources (Patient, Observation, Medication, Condition, AllergyIntolerance, Encounter, Immunization, DocumentReference, FamilyMemberHistory) and provides a generic fallback for any other resource. Minor gaps exist (no dedicated cross-resource search or batch operations) but agents can work around them.
Maintenance
Related MCP Connectors
Hosted MCP server for the Healthie EHR & telehealth API: patients, appointments, charting, tasks.
Hosted MCP server exposing US hospital procedure cost data to AI assistants
MCP server unifying ERPs, CRMs, APIs and knowledge base for Claude, ChatGPT and Gemini.
Free hosted MCP server: US healthcare procedure cost estimates and provider pricing. No API key.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceAn MCP server that brings AI-powered search and conversation to your FHIR clinical documents.1MIT

LangCare MCP FHIR Serverofficial
AlicenseNot gradedqualityDmaintenanceEnterprise-grade MCP Server for FHIR-based EMRs. Enables AI agents to read, search, create, and update any FHIR R4 resource across major EHR systems like EPIC, Cerner, and OpenEMR.410 npm75MIT- FlicenseNot gradedqualityAmaintenanceEnables LLM-based agents and MCP-compatible clients to query and manipulate FHIR-compliant clinical data using natural-language prompts, offering full CRUD operations on FHIR resources, semantic document search, RAG pipelines, and LOINC terminology lookup.-
- FlicenseNot gradedqualityAmaintenanceEnables MCP-compatible clients and LLM agents to perform full CRUD operations on FHIR resources, query and manipulate clinical data through natural-language prompts, and use document ingestion, semantic search, and terminology lookup against a FHIR backend.-