fhir

FHIR MCP Server provides a modular interface to manage FHIR resources via MCP-compatible tools. It exposes a suite of MCP Tools designed to interact with a FHIR backend (e.g., Medplum) for CRUD operations, resource-specific tooling, and integration with auxiliary services like a vector store for semantic search. The server is designed to be compatible with standard MCP clients, enabling natural-language prompts to trigger resource queries, create or update resources, and perform complex workflows across patients, conditions, medications, encounters, and more. In addition to CRUD, the server offers document processing, RAG-based retrieval, and LOINC terminology lookups to support clinical reasoning and validation. When deploying with Docker or uv, you can configure authentication, transport mode, and integration endpoints via environment variables.

Prerequisites:

• Docker (recommended) or uv (Python/uv) installed on the host
• Access to a FHIR server (e.g., Medplum)
• Pinecone API key for vector-based search (optional but required for semantic retrieval)
• LOINC API access (optional but recommended)

Installation & Setup

1. Clone the repository:

git clone https://github.com/the-momentum/fhir-mcp-server
cd fhir-mcp-server

2. Set up environment variables:

cp config/.env.example config/.env

Edit config/.env with your credentials and configuration. See Environment Variables documentation in the repo for details.

3. Install dependencies and build (Docker-based):

make build

Or, for uv-based execution:

make uv

4. Update MCP Client configuration (example snippets provided in the README under Docker and uv setups):

• Docker example config snippet:

{
  "mcpServers": {
    "docker-mcp-server": {
      "command": "docker",
      "args": [
        "run","-i","--rm","--init","--name","fhir-mcp-server",
        "--mount", "type=bind,source=<your-project-path>/app,target=/root_project/app",
        "--mount", "type=bind,source=<your-project-path>/config/.env,target=/root_project/config/.env",
        "-e", "TRANSPORT_MODE=stdio",
        "mcp-server:latest"
      ]
    }
  }
}

• uv example config snippet (as shown in the README):

{
  "mcpServers": {
    "uv-mcp-server": {
      "command": "uvx",
      "args": [
        "<package-name>"
      ]
    }
  }
}

5. Start the server using your chosen deployment method (Docker or uv) and verify that MCP clients can connect using the configured transport and endpoints.

Environment variables play a critical role in configuring connections to the FHIR backend, Pinecone, and LOINC services. Common issues include invalid API keys, incorrect FHIR server URLs, and transport mode mismatches (stdio vs http/https). If you enable Docker mounts for code and config, ensure file permissions are correct and paths use absolute paths. For semantic search, ensure Pinecone is reachable and the index name matches your setup. Review the MCP Tools section to understand resource-specific operations available to clients, such as request_patient_resource, request_condition_resource, and request_medication_resource.