home / mcp / fhir mcp server

FHIR MCP Server

Provides an MCP bridge to FHIR APIs enabling search, read, create, update, and delete operations via multiple transports.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "wso2-fhir-mcp-server": {
      "url": "http://localhost:8000/mcp",
      "headers": {
        "FHIR_MCP_HOST": "localhost",
        "FHIR_MCP_PORT": "8000",
        "FHIR_MCP_SERVER_URL": "https://mcp.example.com/mcp",
        "FHIR_SERVER_CLIENT_ID": "YOUR_CLIENT_ID",
        "FHIR_MCP_REQUEST_TIMEOUT": "30",
        "FHIR_SERVER_DISABLE_AUTHORIZATION": "True"
      }
    }
  }
}

You operate a Model Context Protocol (MCP) server that exposes FHIR APIs in a flexible, transport-agnostic way. It lets you search, retrieve, and analyze clinical data from FHIR servers using modern tooling and client applications. By supporting multiple transport methods and OAuth2-based authentication, it integrates smoothly with MCP clients and AI-assisted workflows, enabling secure, scalable access to healthcare data.

How to use

Connect client tools to your MCP server using either the HTTP transport or the local STDIO transport. With HTTP, your MCP server acts as a remote endpoint you reach at a URL such as http://localhost:8000/mcp. With STDIO, you run the MCP server locally and it communicates via the standard input/output streams.

Configure secure access by supplying OAuth2 credentials to authorize requests against your FHIR server. You can enable or disable authorization as needed. When authorization is enabled, ensure you provide a client ID, client secret, base URL for the FHIR server, and the required scopes. If you prefer not to use OAuth2, you can disable authorization to connect to publicly accessible FHIR endpoints.

How to install

Prerequisites you need before you install the MCP server: Python 3.8 or newer, and a tool to manage dependencies. You should also have access to a FHIR API server.

Install using the PyPI package and run the server:

uvx fhir-mcp-server

Install from source by cloning the project, creating a virtual environment, installing dependencies, and running the server:

# 1) Clone the repository
git clone <repository_url>
cd <repository_directory>

# 2) Create and activate a virtual environment
uv venv
source .venv/bin/activate
uv pip sync requirements.txt

# Or using pip directly
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

# 3) Configure environment and run
cp .env.example .env
uv run fhir-mcp-server

Install using Docker to run in an isolated container. Build the image or pull from the registry, then run the container with environment configuration:

# Build from source
docker build -t fhir-mcp-server .

# Or pull from registry
docker pull wso2/fhir-mcp-server:latest

# Run with environment variables loaded from a file
docker run --env-file .env -p 8000:8000 fhir-mcp-server

Configuration

The MCP server uses environment variables to configure access to the FHIR server and to control its own behavior. Key variables include those that enable or disable authorization, set the FHIR server base URL, and specify OAuth2 client credentials and scopes.

Examples of common environment variables include setting the FHIR server base URL, client ID, client secret, and scopes to request during OAuth2 flows. You can also set a specific host and port for the MCP server to listen on.

If you want to run the server behind a proxy or with a custom URL, you can provide a base URL that overrides the generated one.

Security and access control

Authentication for MCP clients is provided via SMART-on-FHIR style OAuth2 flows. When enabled, clients must obtain and present an access token to access FHIR data. You can disable authorization if you are connecting to publicly accessible FHIR servers for testing.

Usage samples and integration steps

To integrate with common MCP clients, you can connect via HTTP at http://localhost:8000/mcp or use the STDIO transport by running the server locally and wiring it through the MCP client’s STDIO channel. You can also connect via SSE transport for streaming capabilities.

Troubleshooting notes

Ensure the FHIR server is reachable at the configured base URL and that OAuth2 credentials (if used) are valid. If you encounter connection problems, verify that the MCP server is listening on the expected host/port and that the transport configuration matches your client.

Example MCP connection configurations

[
  {
    "type": "http",
    "name": "fhir_http",
    "url": "http://localhost:8000/mcp",
    "args": []
  },
  {
    "type": "stdio",
    "name": "fhir_stdio",
    "command": "uv",
    "args": ["--directory", "/path/to/fhir-mcp-server", "run", "fhir-mcp-server", "--transport", "stdio"],
    "env": [
      {"name": "FHIR_SERVER_ACCESS_TOKEN", "value": "YOUR_TOKEN"}
    ]
  }
]

Available tools

get_capabilities

Retrieves metadata about a specified FHIR resource type, including supported search parameters and custom operations.

search

Executes a standard FHIR search on a given resource type and returns matching resources.

read

Performs a FHIR read interaction to retrieve a resource by type and ID, with optional search parameters and operations.

create

Creates a new resource of a given FHIR type with a provided payload and optional parameters.

update

Updates an existing resource by ID with a new payload and optional parameters.

delete

Deletes a specific resource by type and ID with optional parameters.

get_user

Retrieves the currently authenticated user's FHIR resource profile.