# wso2/fhir-mcp-server [Health: Active]

**Category:** 🧬 Biology & Bioinformatics  
**Repository:** https://github.com/wso2/fhir-mcp-server  
**GitHub Stars:** 137  
**Views:** 6  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/wso2-fhir-mcp-server

## Description
Model Context Protocol server for Fast Healthcare Interoperability Resources (FHIR) APIs. Provides seamless integration with FHIR servers, enabling AI assistants to search, retrieve, create, update, and analyze clinical healthcare data with SMART-on-FHIR authentication support.

## Tools
Capabilities this server exposes over MCP:

- **get_capabilities** — Retrieves metadata about a specified FHIR resource type, including its supported search parameters and custom operations.
- **type** — The FHIR resource type name (e.g., "Patient", "Observation", "Encounter")
- **search** — Executes a standard FHIR search interaction on a given resource type, returning a bundle or list of matching resources.
- **searchParam** — A mapping of FHIR search parameter names to their desired values (e.g., {"family":"Simpson","birthdate":"1956-05-12"}).
- **response_filter_fhirpaths** — (Optional) An array of FHIRPath expressions (e.g., `["Patient.name", "Patient.birthDate", "Bundle.link.where(relation='next').url"]`) to apply to the resources in the response bundle.
- **read** — Performs a FHIR "read" interaction to retrieve a single resource instance by its type and resource ID, optionally refining the response with search parameters or custom operations.
- **id** — The logical ID of a specific FHIR resource instance.
- **operation** — The name of a custom FHIR operation or extended query defined for the resource (e.g., "$everything").
- **create** — Executes a FHIR "create" interaction to persist a new resource of the specified type.
- **payload** — A JSON object representing the full FHIR resource body to be created.
- **update** — Performs a FHIR "update" interaction by replacing an existing resource instance's content with the provided payload.
- **delete** — Execute a FHIR "delete" interaction on a specific resource instance.
- **get_user** — Retrieves the currently authenticated user's FHIR resource (for example the linked `Patient` resource) and returns a concise profile containing available demographic fields such as `id`, `name`, and `birthDate`.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `uvx` (confidence: high):

```json
"mcpServers": {
  "fhir-mcp-server": {
    "command": "uvx",
    "args": ["fhir-mcp-server"],
    "env": {
      "FHIR_SERVER_BASE_URL": "",
      "FHIR_SERVER_CLIENT_ID": "",
      "FHIR_SERVER_CLIENT_SECRET": "",
      "FHIR_SERVER_SCOPES": "",
      "FHIR_SERVER_DISABLE_AUTHORIZATION": "",
      "FHIR_MCP_HOST": "",
      "FHIR_MCP_PORT": ""
    }
  }
}
```

**Requires environment variables:** `FHIR_SERVER_BASE_URL`, `FHIR_SERVER_CLIENT_ID`, `FHIR_SERVER_CLIENT_SECRET`, `FHIR_SERVER_SCOPES`, `FHIR_SERVER_DISABLE_AUTHORIZATION`, `FHIR_MCP_HOST`, `FHIR_MCP_PORT` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What wso2/fhir-mcp-server does

wso2/fhir-mcp-server exposes FHIR API operations through the Model Context Protocol. It gives an MCP client access to resource metadata, standard searches, individual resource reads, custom operations, and write operations. Supported writes include creating a resource, replacing an existing resource with an update, and deleting a resource instance.

The server also provides a user-focused lookup that returns the authenticated user’s FHIR resource, such as a linked Patient record, with concise demographic fields including an ID, name, and birth date. This can support assistants that need to identify the current user before querying related data.

## How it works

The server targets an externally accessible FHIR API configured through its base URL. MCP clients communicate with it over stdio, Server-Sent Events, or streamable HTTP. The default network endpoint listens on localhost port 8000 when the HTTP-based configuration is used, with host and port settings available for customization.

Authentication uses SMART-on-FHIR settings by default. Client credentials and requested scopes are supplied through environment variables, while authorization can be disabled for suitable local or unauthenticated FHIR environments. The repository demonstrates connections to a public HAPI FHIR server and an Epic sandbox, including an OAuth 2.0 authorization code flow for the latter.

Search accepts a FHIR resource type and a mapping of search parameter names to values, then returns matching resources in a bundle or list. Reads can target a resource ID and can invoke a custom operation such as `$everything`. Search and read results may be narrowed with FHIRPath expressions, including paths that select fields or retrieve a pagination link.

## Setup and configuration

Python 3.8 or newer and an accessible FHIR API are prerequisites. The package can be run with `uvx fhir-mcp-server`, or installed from source in a virtual environment using `uv` or `pip`. A Docker image is also available, and the project includes a Docker Compose setup that starts a WSO2 FHIR Server with PostgreSQL alongside the MCP server.

At minimum, configure `FHIR_SERVER_BASE_URL`. With authorization enabled, also configure `FHIR_SERVER_CLIENT_ID`, `FHIR_SERVER_CLIENT_SECRET`, and `FHIR_SERVER_SCOPES`. For an unauthenticated local setup, set `FHIR_SERVER_DISABLE_AUTHORIZATION=True`. `FHIR_MCP_HOST` and `FHIR_MCP_PORT` change the MCP server’s bind address and port. Environment variables can be exported directly or placed in a `.env` file.

VS Code and Claude Desktop are documented MCP client integrations. MCP Inspector is also listed as a client for testing or inspecting the server.

## Tools and capabilities

- `get_capabilities` reports metadata for a FHIR resource type, including available search parameters and custom operations.
- `search` performs a standard FHIR search and accepts optional FHIRPath response filtering.
- `read` retrieves one resource by type and ID, with support for optional parameters and custom operations.
- `create` persists a supplied JSON FHIR resource.
- `update` replaces the contents of an existing resource with a supplied payload.
- `delete` removes a specified resource instance.
- `get_user` returns a concise profile for the authenticated user’s FHIR resource.

## Limitations and notes

The server depends on a reachable FHIR API and on that API supporting the requested resource types, parameters, and operations. Authentication settings must match the target FHIR deployment. For local Docker or Docker Compose use, the project recommends disabling authorization. The Compose configuration is intended for development and removes database data when `docker compose down` is used; `docker compose stop` preserves it between runs.

_Full upstream README: https://allmcps.com/mcp/wso2-fhir-mcp-server/readme_