# Model Context Protocol (MCP) Server for Fast Healthcare Interoperability Resources (FHIR) APIs
[](https://github.com/wso2/fhir-mcp-server/blob/main/LICENSE)
[](https://stackoverflow.com/questions/tagged/wso2)
[](https://discord.com/invite/wso2)
[](https://twitter.com/intent/follow?screen_name=wso2)
## Table of Contents
- [Overview](#overview)
- [Demo](#demo)
- [Demo with HAPI FHIR server](#demo-with-hapi-fhir-server)
- [Demo with EPIC Sandbox](#demo-with-epic-sandbox)
- [Core Features](#core-features)
- [Prerequisites](#prerequisites)
- [Installation](#installation)
- [Installing using PyPI Package](#installing-using-pypi-package)
- [Installing from Source](#installing-from-source)
- [Installing using Docker](#installing-using-docker)
- [Integration with MCP Clients](#integration-with-mcp-clients)
- [VS Code](#vs-code)
- [Claude Desktop](#claude-desktop)
- [MCP Inspector](#mcp-inspector)
- [Configuration](#configuration)
- [CLI Options](#cli-options)
- [Environment Variables](#environment-variables)
- [Tools](#tools)
- [Development & Testing](#development--testing)
- [Installing Development Dependencies](#installing-development-dependencies)
- [Running Tests](#running-tests)
## Overview
The FHIR MCP Server is a Model Context Protocol (MCP) server that provides seamless integration with FHIR APIs. Designed for developers, integrators, and healthcare innovators, this server acts as a bridge between modern AI/LLM tools and healthcare data, making it easy to search, retrieve, and analyze clinical information.
## Demo
### Demo with HAPI FHIR server
This video showcases the MCP server's functionality when connected to a public [HAPI FHIR server](https://hapi.fhir.org/). This example showcases direct interaction with an open FHIR server that does not require an authorization flow.
https://github.com/user-attachments/assets/899874d6-df6f-4400-9d72-0682e225abbd
### Demo with EPIC Sandbox
This video showcases the MCP server's capabilities within the [Epic EHR ecosystem](https://open.epic.com/). It demonstrates the complete OAuth 2.0 Authorization Code Grant flow.
https://github.com/user-attachments/assets/f73a3666-b291-4ede-a253-ea7aaf405c12
## Core Features
- **MCP-compatible transport**: Serves FHIR via stdio, SSE, or streamable HTTP
- **SMART-on-FHIR based authentication support**: Securely authenticate with FHIR servers and clients
- **Tool integration**: Integratable with any MCP client such as VS Code, Claude Desktop, and MCP Inspector
## Prerequisites
- Python 3.8+
- [uv](https://github.com/astral-sh/uv) (for dependency management)
- An accessible FHIR API server.
## Installation
You can use the FHIR MCP Server by installing our Python package, by cloning this repository or by running as a docker container.
### Installing using PyPI Package
1. **Configure Environment Variables:**
To run the server, you must set `FHIR_SERVER_BASE_URL`. If you plan to use authorization, you'll also need to configure `FHIR_SERVER_CLIENT_ID`, `FHIR_SERVER_CLIENT_SECRET`, and `FHIR_SERVER_SCOPES`. By default, the MCP server will listen on http://localhost:8000. You can customize the host and port by setting `FHIR_MCP_HOST` and `FHIR_MCP_PORT` respectively.
You can set these by exporting them as environment variables like below or by creating a `.env` file (referencing `.env.example`).
```bash
export FHIR_SERVER_BASE_URL=""
export FHIR_SERVER_CLIENT_ID=""
export FHIR_SERVER_CLIENT_SECRET=""
export FHIR_SERVER_SCOPES=""
export FHIR_MCP_HOST="localhost"
export FHIR_MCP_PORT="8000"
```
2. **Install the PyPI package and run the server**
If you are exposing a FHIR server with no security:
```bash
uvx fhir-mcp-server --disable-auth
```
else;
```bash
uvx fhir-mcp-server
```
### Installing from Source
1. **Clone the repository:**
```bash
git clone <repository_url>
cd <repository_directory>
```
2. **Create a virtual environment and install dependencies:**
```bash
uv venv
source .venv/bin/activate
uv pip sync requirements.txt
```
Or with pip:
```bash
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```
3. **Configure Environment Variables:**
Copy the example file and customize if needed:
```bash
cp .env.example .env
```
4. **Run the server:**
```bash
uv run fhir-mcp-server
```
### Installing using Docker
You can run the MCP server using Docker for a consistent, isolated environment.
1. Build the Docker Image
```bash
docker build -t fhir-mcp-server .
```
2. Configure Environment Variables
Copy the example environment file and edit as needed:
```bash
cp .env.example .env
# Edit .env to set your FHIR server, client credentials, etc.
```
Alternatively, you can pass environment variables directly with `-e` flags or use Docker secrets for sensitive values.
3. Run the Container
```bash
docker run --env-file .env -p 8000:8000 fhir-mcp-server
```
This will start the server and expose it on port 8000. Adjust the port mapping as needed.
## Integration with MCP Clients
The FHIR MCP Server is designed for seamless integration with various MCP clients.
### VS Code
[](https://insiders.vscode.dev/redirect/mcp/install?name=fhir&config=%7B%22type%22%3A%22http%22%2C%22url%22%3A%22http%3A%2F%2Flocalhost%3A8000%2Fmcp%2F%22%7D)
[](https://insiders.vscode.dev/redirect/mcp/install?name=fhir&config=%7B%22type%22%3A%22http%22%2C%22url%22%3A%22http%3A%2F%2Flocalhost%3A8000%2Fmcp%2F%22%7D)
Add the following JSON block to your User Settings (JSON) file in VS Code (> V1.101). You can do this by pressing Ctrl + Shift + P and typing Preferences: Open User Settings (JSON).
<table>
<tr><th>Streamable HTTP</th><th>STDIO</th><th>SSE</th></tr>
<tr valign=top>
<td>
```json
"mcp": {
"servers": {
"fhir": {
"type": "http",
"url": "http://localhost:8000/mcp",
}
}
}
```
</td>
<td>
```json
"mcp": {
"servers": {
"fhir": {
"command": "uv",
"args": [
"--directory",
"/path/to/fhir-mcp-server",
"run",
"fhir-mcp-server",
"--transport",
"stdio"
],
"env": {
"FHIR_SERVER_ACCESS_TOKEN": "Your FHIR Access Token"
}
}
}
}
```
</td>
<td>
```json
"mcp": {
"servers": {
"fhir": {
"type": "sse",
"url": "http://localhost:8000/sse",
}
}
}
```
</td>
</tr>
</table>
### Claude Desktop
Add the following JSON block to your Claude Desktop settings to connect to your local MCP server.
- Launch the Claude Desktop app, click on the Claude menu in the top bar, and select "Settings…".
- In the Settings pane, click “Developer” in the left sidebar. Then click "Edit Config". This will open your configuration file in your file system. If it doesn’t exist yet, Claude will create one automatically at:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
- Open the claude_desktop_config.json file in any text editor. Replace its contents with the following JSON block to register the MCP server:
<table>
<tr><th>Streamable HTTP</th><th>STDIO</th><th>SSE</th></tr>
<tr valign=top>
<td>
```json
{
"mcpServers": {
"fhir": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"http://localhost:8000/mcp"
]
}
}
}
```
</td>
<td>
```json
{
"mcpServers": {
"fhir": {
"command": "uv",
"args": [
"--directory",
"/path/to/fhir-mcp-server",
"run",
"fhir-mcp-server",
"--transport",
"stdio"
],
"env": {
"FHIR_SERVER_ACCESS_TOKEN": "Your FHIR Access Token"
}
}
}
}
```
</td>
<td>
```json
{
"mcpServers": {
"fhir": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"http://localhost:8000/sse"
]
}
}
}
```
</td>
</tr>
</table>
### MCP Inspector
Follow these steps to get the MCP Inspector up and running:
- Open a terminal and run the following command:
`npx -y @modelcontextprotocol/inspector`
- In the MCP Inspector interface:
<table>
<tr><th>Streamable HTTP</th><th>STDIO</th><th>SSE</th></tr>
<tr valign=top>
<td>
- Transport Type: `Streamable HTTP`
- URL: `http://localhost:8000/mcp`
</td>
<td>
- Transport Type: `STDIO`
- Command: `uv`
- Arguments: `--directory /path/to/fhir-mcp-server run fhir-mcp-server --transport stdio`
</td>
<td>
- Transport Type: `SSE`
- URL: `http://localhost:8000/sse`
</td>
</tr>
</table>
Make sure your MCP server is already running and listening on the above endpoint.
Once connected, MCP Inspector will allow you to visualize tool invocations, inspect request/response payloads, and debug your tool implementations easily.
## Configuration
### CLI Options
You can customize the behavior of the MCP server using the following command-line flags:
- **--transport**
- Description: Specifies the transport protocol used by the MCP server to communicate with clients.
- Accepted values: stdio, sse, streamable-http
- Default: streamable-http
- **--log-level**
- Description: Sets the logging verbosity level for the server.
- Accepted values: DEBUG, INFO, WARN, ERROR (case-insensitive)
- Default: INFO
- **--disable-auth**
- Description: Disables the security of the MCP Server. Allows you to connect with openly available FHIR servers.
- Type: Flag (no value required)
- Default: False (authentication enabled)
- **--help**
- Description: Displays a help message with available server options and exits.
- Usage: Automatically provided by the command-line interface.
Sample Usages:
```shell
uv run fhir-mcp-server --transport streamable-http --log-level DEBUG --disable-auth
uv run fhir-mcp-server --help
```
### Environment Variables
**MCP Server Configurations:**
- `FHIR_MCP_HOST`: The hostname or IP address the MCP server should bind to (e.g., `localhost` for local-only access, or `0.0.0.0` for all interfaces).
- `FHIR_MCP_PORT`: The port on which the MCP server will listen for incoming client requests (e.g., `8000`).
- `FHIR_MCP_SERVER_URL`: If set, this value will be used as the server's base URL instead of generating it from host and port. Useful for custom URL configurations or when behind a proxy.
- `FHIR_MCP_REQUEST_TIMEOUT`: Timeout duration in seconds for requests from the MCP server to the FHIR server (default: `30`).
**MCP Server OAuth2 with FHIR server Configuration (MCP Client ↔ MCP Server):**
These variables configure the MCP client's secure connection to the MCP server, using the OAuth2 authorization code grant flow with a FHIR server.
- `FHIR_SERVER_CLIENT_ID`: The OAuth2 client ID used to authorize MCP clients with the FHIR server.
- `FHIR_SERVER_CLIENT_SECRET`: The client secret corresponding to the FHIR client ID. Used during token exchange.
- `FHIR_SERVER_BASE_URL`: The base URL of the FHIR server (e.g., `https://hapi.fhir.org/baseR4`). This is used to generate tool URIs and to route FHIR requests.
- `FHIR_SERVER_SCOPES`: A space-separated list of OAuth2 scopes to request from the FHIR authorization server (e.g., `user/Patient.read user/Observation.read`).
- `FHIR_SERVER_ACCESS_TOKEN`: The access token to use for authenticating requests to the FHIR server. If this variable is set, the server will bypass the OAuth2 authorization flow and use this token directly for all requests.
## Tools
- `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.
- `type`: The FHIR resource type name (e.g., "MedicationRequest", "Condition", "Procedure").
- `searchParam`: A mapping of FHIR search parameter names to their desired values (e.g., {"family":"Simpson","birthdate":"1956-05-12"}).
- `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.
- `type`: The FHIR resource type name (e.g., "DiagnosticReport", "AllergyIntolerance", "Immunization").
- `id`: The logical ID of a specific FHIR resource instance.
- `searchParam`: A mapping of FHIR search parameter names to their desired values (e.g., {"device-name":"glucometer"}).
- `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.
- `type`: The FHIR resource type name (e.g., "Device", "CarePlan", "Goal").
- `payload`: A JSON object representing the full FHIR resource body to be created.
- `searchParam`: A mapping of FHIR search parameter names to their desired values (e.g., {"address-city":"Boston"}).
- `operation`: The name of a custom FHIR operation or extended query defined for the resource (e.g., "$evaluate").
- `update`: Performs a FHIR "update" interaction by replacing an existing resource instance's content with the provided payload.
- `type`: The FHIR resource type name (e.g., "Location", "Organization", "Coverage").
- `id`: The logical ID of a specific FHIR resource instance.
- `payload`: The complete JSON representation of the FHIR resource, containing all required elements and any optional data.
- `searchParam`: A mapping of FHIR search parameter names to their desired values (e.g., {"patient":"Patient/54321","relationship":"father"}).
- `operation`: The name of a custom FHIR operation or extended query defined for the resource (e.g., "$lastn").
- `delete`: Execute a FHIR "delete" interaction on a specific resource instance.
- `type`: The FHIR resource type name (e.g., "ServiceRequest", "Appointment", "HealthcareService").
- `id`: The logical ID of a specific FHIR resource instance.
- `searchParam`: A mapping of FHIR search parameter names to their desired values (e.g., {"category":"laboratory","issued:"2025-05-01"}).
- `operation`: The name of a custom FHIR operation or extended query defined for the resource (e.g., "$expand").
## Development & Testing
### Installing Development Dependencies
To run tests and contribute to development, install the test dependencies:
**Using pip:**
```bash
# Install project in development mode with test dependencies
pip install -e '.[test]'
# Or install from requirements file
pip install -r requirements-dev.txt
```
**Using uv:**
```bash
# Install development dependencies
uv sync --dev
```
### Running Tests
The project includes a comprehensive test suite covering all major functionality:
```bash
# Simple test runner
python run_tests.py
# Or direct pytest usage
PYTHONPATH=src python -m pytest tests/ -v --cov=src/fhir_mcp_server
```
**Using pytest:**
```bash
pytest tests/
```
This will discover and run all tests in the `tests/` directory.
**Test Features:**
- **100+ tests** with comprehensive coverage
- **Full async/await support** using pytest-asyncio
- **Complete mocking** of HTTP requests and external dependencies
- **Coverage reporting** with terminal and HTML output
- **Fast execution** with no real network calls
The test suite includes:
- **Unit tests**: Core functionality testing
- **Integration tests**: Component interaction validation
- **Edge case coverage**: Error handling and validation scenarios
- **Mocked OAuth flows**: Realistic authentication testing
Coverage reports are generated in `htmlcov/index.html` for detailed analysis.
Raw data
{
"_id": null,
"home_page": null,
"name": "fhir-mcp-server",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": null,
"keywords": "fhir, healthcare, llm, mcp, model-context-protocol, modelcontextprotocol",
"author": null,
"author_email": "Vimukthi Rajapaksha <vimukthir@wso2.com>, Joel Sathiyendra <joel@wso2.com>, Nirmal Fernando <nirmal@wso2.com>",
"download_url": "https://files.pythonhosted.org/packages/42/73/b6d52d628a46c6d5f1e5daaf0d7a306dab1a95967b4c574244931081d941/fhir_mcp_server-0.9.0.tar.gz",
"platform": null,
"description": "# Model Context Protocol (MCP) Server for Fast Healthcare Interoperability Resources (FHIR) APIs\n\n[](https://github.com/wso2/fhir-mcp-server/blob/main/LICENSE)\n[](https://stackoverflow.com/questions/tagged/wso2)\n[](https://discord.com/invite/wso2)\n[](https://twitter.com/intent/follow?screen_name=wso2)\n\n## Table of Contents\n- [Overview](#overview)\n- [Demo](#demo)\n - [Demo with HAPI FHIR server](#demo-with-hapi-fhir-server)\n - [Demo with EPIC Sandbox](#demo-with-epic-sandbox)\n- [Core Features](#core-features)\n- [Prerequisites](#prerequisites)\n- [Installation](#installation)\n - [Installing using PyPI Package](#installing-using-pypi-package)\n - [Installing from Source](#installing-from-source)\n - [Installing using Docker](#installing-using-docker)\n- [Integration with MCP Clients](#integration-with-mcp-clients)\n - [VS Code](#vs-code)\n - [Claude Desktop](#claude-desktop)\n - [MCP Inspector](#mcp-inspector)\n- [Configuration](#configuration)\n - [CLI Options](#cli-options)\n - [Environment Variables](#environment-variables)\n- [Tools](#tools)\n- [Development & Testing](#development--testing)\n - [Installing Development Dependencies](#installing-development-dependencies)\n - [Running Tests](#running-tests)\n\n\n## Overview\n\nThe FHIR MCP Server is a Model Context Protocol (MCP) server that provides seamless integration with FHIR APIs. Designed for developers, integrators, and healthcare innovators, this server acts as a bridge between modern AI/LLM tools and healthcare data, making it easy to search, retrieve, and analyze clinical information.\n\n## Demo\n\n### Demo with HAPI FHIR server\n\nThis video showcases the MCP server's functionality when connected to a public [HAPI FHIR server](https://hapi.fhir.org/). This example showcases direct interaction with an open FHIR server that does not require an authorization flow.\n\nhttps://github.com/user-attachments/assets/899874d6-df6f-4400-9d72-0682e225abbd\n\n### Demo with EPIC Sandbox\n\nThis video showcases the MCP server's capabilities within the [Epic EHR ecosystem](https://open.epic.com/). It demonstrates the complete OAuth 2.0 Authorization Code Grant flow.\n\nhttps://github.com/user-attachments/assets/f73a3666-b291-4ede-a253-ea7aaf405c12\n\n## Core Features\n\n- **MCP-compatible transport**: Serves FHIR via stdio, SSE, or streamable HTTP\n\n- **SMART-on-FHIR based authentication support**: Securely authenticate with FHIR servers and clients\n\n- **Tool integration**: Integratable with any MCP client such as VS Code, Claude Desktop, and MCP Inspector\n\n## Prerequisites\n\n- Python 3.8+\n- [uv](https://github.com/astral-sh/uv) (for dependency management)\n- An accessible FHIR API server.\n\n## Installation\n\nYou can use the FHIR MCP Server by installing our Python package, by cloning this repository or by running as a docker container.\n\n### Installing using PyPI Package\n\n1. **Configure Environment Variables:**\n\n To run the server, you must set `FHIR_SERVER_BASE_URL`. If you plan to use authorization, you'll also need to configure `FHIR_SERVER_CLIENT_ID`, `FHIR_SERVER_CLIENT_SECRET`, and `FHIR_SERVER_SCOPES`. By default, the MCP server will listen on http://localhost:8000. You can customize the host and port by setting `FHIR_MCP_HOST` and `FHIR_MCP_PORT` respectively.\n\n You can set these by exporting them as environment variables like below or by creating a `.env` file (referencing `.env.example`).\n\n ```bash \n export FHIR_SERVER_BASE_URL=\"\"\n export FHIR_SERVER_CLIENT_ID=\"\"\n export FHIR_SERVER_CLIENT_SECRET=\"\"\n export FHIR_SERVER_SCOPES=\"\"\n\n export FHIR_MCP_HOST=\"localhost\"\n export FHIR_MCP_PORT=\"8000\"\n ```\n\n2. **Install the PyPI package and run the server**\n\n If you are exposing a FHIR server with no security:\n\n ```bash\n uvx fhir-mcp-server --disable-auth\n ```\n\n else;\n ```bash\n uvx fhir-mcp-server\n ```\n\n### Installing from Source\n\n1. **Clone the repository:**\n ```bash\n git clone <repository_url>\n cd <repository_directory>\n ```\n\n2. **Create a virtual environment and install dependencies:**\n ```bash\n uv venv\n source .venv/bin/activate\n uv pip sync requirements.txt\n ```\n Or with pip:\n ```bash\n python -m venv .venv\n source .venv/bin/activate\n pip install -r requirements.txt\n ```\n\n3. **Configure Environment Variables:**\n Copy the example file and customize if needed:\n ```bash\n cp .env.example .env\n ```\n\n4. **Run the server:**\n ```bash\n uv run fhir-mcp-server\n ```\n\n### Installing using Docker\n\nYou can run the MCP server using Docker for a consistent, isolated environment. \n\n1. Build the Docker Image\n\n ```bash\n docker build -t fhir-mcp-server .\n ```\n\n2. Configure Environment Variables\n\n Copy the example environment file and edit as needed:\n\n ```bash\n cp .env.example .env\n # Edit .env to set your FHIR server, client credentials, etc.\n ```\n\n Alternatively, you can pass environment variables directly with `-e` flags or use Docker secrets for sensitive values.\n\n3. Run the Container\n\n ```bash\n docker run --env-file .env -p 8000:8000 fhir-mcp-server\n ```\n\n This will start the server and expose it on port 8000. Adjust the port mapping as needed.\n\n## Integration with MCP Clients\n\nThe FHIR MCP Server is designed for seamless integration with various MCP clients.\n\n### VS Code\n\n[](https://insiders.vscode.dev/redirect/mcp/install?name=fhir&config=%7B%22type%22%3A%22http%22%2C%22url%22%3A%22http%3A%2F%2Flocalhost%3A8000%2Fmcp%2F%22%7D)\n[](https://insiders.vscode.dev/redirect/mcp/install?name=fhir&config=%7B%22type%22%3A%22http%22%2C%22url%22%3A%22http%3A%2F%2Flocalhost%3A8000%2Fmcp%2F%22%7D)\n\nAdd the following JSON block to your User Settings (JSON) file in VS Code (> V1.101). You can do this by pressing Ctrl + Shift + P and typing Preferences: Open User Settings (JSON).\n\n<table>\n<tr><th>Streamable HTTP</th><th>STDIO</th><th>SSE</th></tr>\n<tr valign=top>\n<td>\n\n```json\n\"mcp\": {\n \"servers\": {\n \"fhir\": {\n \"type\": \"http\",\n \"url\": \"http://localhost:8000/mcp\",\n }\n }\n}\n```\n</td>\n\n<td>\n\n```json\n\"mcp\": {\n \"servers\": {\n \"fhir\": {\n \"command\": \"uv\",\n \"args\": [\n \"--directory\",\n \"/path/to/fhir-mcp-server\",\n \"run\",\n \"fhir-mcp-server\",\n \"--transport\",\n \"stdio\"\n ],\n \"env\": {\n \"FHIR_SERVER_ACCESS_TOKEN\": \"Your FHIR Access Token\"\n }\n }\n }\n}\n```\n</td>\n\n<td>\n\n```json\n\"mcp\": {\n \"servers\": {\n \"fhir\": {\n \"type\": \"sse\",\n \"url\": \"http://localhost:8000/sse\",\n }\n }\n}\n```\n</td>\n</tr>\n</table>\n\n### Claude Desktop\nAdd the following JSON block to your Claude Desktop settings to connect to your local MCP server. \n - Launch the Claude Desktop app, click on the Claude menu in the top bar, and select \"Settings\u2026\".\n - In the Settings pane, click \u201cDeveloper\u201d in the left sidebar. Then click \"Edit Config\". This will open your configuration file in your file system. If it doesn\u2019t exist yet, Claude will create one automatically at:\n - macOS: ~/Library/Application Support/Claude/claude_desktop_config.json\n - Windows: %APPDATA%\\Claude\\claude_desktop_config.json\n - Open the claude_desktop_config.json file in any text editor. Replace its contents with the following JSON block to register the MCP server:\n\n<table>\n<tr><th>Streamable HTTP</th><th>STDIO</th><th>SSE</th></tr>\n<tr valign=top>\n<td>\n\n```json\n{\n \"mcpServers\": {\n \"fhir\": {\n \"command\": \"npx\",\n \"args\": [\n \"-y\",\n \"mcp-remote\",\n \"http://localhost:8000/mcp\"\n ]\n }\n }\n}\n```\n</td>\n<td>\n\n```json\n{\n \"mcpServers\": {\n \"fhir\": {\n \"command\": \"uv\",\n \"args\": [\n \"--directory\",\n \"/path/to/fhir-mcp-server\",\n \"run\",\n \"fhir-mcp-server\",\n \"--transport\",\n \"stdio\"\n ],\n \"env\": {\n \"FHIR_SERVER_ACCESS_TOKEN\": \"Your FHIR Access Token\"\n }\n }\n }\n}\n```\n</td>\n\n<td>\n\n```json\n{\n \"mcpServers\": {\n \"fhir\": {\n \"command\": \"npx\",\n \"args\": [\n \"-y\",\n \"mcp-remote\",\n \"http://localhost:8000/sse\"\n ]\n }\n }\n}\n```\n</td>\n</tr>\n</table>\n\n### MCP Inspector\nFollow these steps to get the MCP Inspector up and running:\n\n- Open a terminal and run the following command:\n \n `npx -y @modelcontextprotocol/inspector`\n\n- In the MCP Inspector interface:\n<table>\n<tr><th>Streamable HTTP</th><th>STDIO</th><th>SSE</th></tr>\n<tr valign=top>\n<td>\n\n- Transport Type: `Streamable HTTP`\n- URL: `http://localhost:8000/mcp`\n</td>\n\n<td>\n\n- Transport Type: `STDIO`\n- Command: `uv`\n- Arguments: `--directory /path/to/fhir-mcp-server run fhir-mcp-server --transport stdio`\n</td>\n\n<td>\n\n- Transport Type: `SSE`\n- URL: `http://localhost:8000/sse`\n</td>\n</tr>\n</table>\n\nMake sure your MCP server is already running and listening on the above endpoint.\n\nOnce connected, MCP Inspector will allow you to visualize tool invocations, inspect request/response payloads, and debug your tool implementations easily.\n\n## Configuration\n\n### CLI Options\n\nYou can customize the behavior of the MCP server using the following command-line flags:\n\n- **--transport**\n - Description: Specifies the transport protocol used by the MCP server to communicate with clients.\n - Accepted values: stdio, sse, streamable-http\n - Default: streamable-http\n\n- **--log-level**\n - Description: Sets the logging verbosity level for the server.\n - Accepted values: DEBUG, INFO, WARN, ERROR (case-insensitive)\n - Default: INFO\n\n- **--disable-auth**\n - Description: Disables the security of the MCP Server. Allows you to connect with openly available FHIR servers.\n - Type: Flag (no value required)\n - Default: False (authentication enabled)\n\n- **--help**\n - Description: Displays a help message with available server options and exits.\n - Usage: Automatically provided by the command-line interface.\n\nSample Usages:\n\n```shell\nuv run fhir-mcp-server --transport streamable-http --log-level DEBUG --disable-auth\nuv run fhir-mcp-server --help\n```\n\n### Environment Variables\n\n**MCP Server Configurations:**\n- `FHIR_MCP_HOST`: The hostname or IP address the MCP server should bind to (e.g., `localhost` for local-only access, or `0.0.0.0` for all interfaces).\n- `FHIR_MCP_PORT`: The port on which the MCP server will listen for incoming client requests (e.g., `8000`).\n- `FHIR_MCP_SERVER_URL`: If set, this value will be used as the server's base URL instead of generating it from host and port. Useful for custom URL configurations or when behind a proxy.\n- `FHIR_MCP_REQUEST_TIMEOUT`: Timeout duration in seconds for requests from the MCP server to the FHIR server (default: `30`).\n\n**MCP Server OAuth2 with FHIR server Configuration (MCP Client \u2194 MCP Server):**\nThese variables configure the MCP client's secure connection to the MCP server, using the OAuth2 authorization code grant flow with a FHIR server.\n\n- `FHIR_SERVER_CLIENT_ID`: The OAuth2 client ID used to authorize MCP clients with the FHIR server.\n- `FHIR_SERVER_CLIENT_SECRET`: The client secret corresponding to the FHIR client ID. Used during token exchange.\n- `FHIR_SERVER_BASE_URL`: The base URL of the FHIR server (e.g., `https://hapi.fhir.org/baseR4`). This is used to generate tool URIs and to route FHIR requests.\n- `FHIR_SERVER_SCOPES`: A space-separated list of OAuth2 scopes to request from the FHIR authorization server (e.g., `user/Patient.read user/Observation.read`).\n- `FHIR_SERVER_ACCESS_TOKEN`: The access token to use for authenticating requests to the FHIR server. If this variable is set, the server will bypass the OAuth2 authorization flow and use this token directly for all requests.\n\n## Tools\n\n- `get_capabilities`: Retrieves metadata about a specified FHIR resource type, including its supported search parameters and custom operations.\n - `type`: The FHIR resource type name (e.g., \"Patient\", \"Observation\", \"Encounter\")\n\n- `search`: Executes a standard FHIR search interaction on a given resource type, returning a bundle or list of matching resources.\n - `type`: The FHIR resource type name (e.g., \"MedicationRequest\", \"Condition\", \"Procedure\").\n - `searchParam`: A mapping of FHIR search parameter names to their desired values (e.g., {\"family\":\"Simpson\",\"birthdate\":\"1956-05-12\"}).\n\n- `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.\n - `type`: The FHIR resource type name (e.g., \"DiagnosticReport\", \"AllergyIntolerance\", \"Immunization\").\n - `id`: The logical ID of a specific FHIR resource instance.\n - `searchParam`: A mapping of FHIR search parameter names to their desired values (e.g., {\"device-name\":\"glucometer\"}).\n - `operation`: The name of a custom FHIR operation or extended query defined for the resource (e.g., \"$everything\").\n\n- `create`: Executes a FHIR \"create\" interaction to persist a new resource of the specified type.\n - `type`: The FHIR resource type name (e.g., \"Device\", \"CarePlan\", \"Goal\").\n - `payload`: A JSON object representing the full FHIR resource body to be created.\n - `searchParam`: A mapping of FHIR search parameter names to their desired values (e.g., {\"address-city\":\"Boston\"}).\n - `operation`: The name of a custom FHIR operation or extended query defined for the resource (e.g., \"$evaluate\").\n\n- `update`: Performs a FHIR \"update\" interaction by replacing an existing resource instance's content with the provided payload.\n - `type`: The FHIR resource type name (e.g., \"Location\", \"Organization\", \"Coverage\").\n - `id`: The logical ID of a specific FHIR resource instance.\n - `payload`: The complete JSON representation of the FHIR resource, containing all required elements and any optional data.\n - `searchParam`: A mapping of FHIR search parameter names to their desired values (e.g., {\"patient\":\"Patient/54321\",\"relationship\":\"father\"}).\n - `operation`: The name of a custom FHIR operation or extended query defined for the resource (e.g., \"$lastn\").\n\n- `delete`: Execute a FHIR \"delete\" interaction on a specific resource instance.\n - `type`: The FHIR resource type name (e.g., \"ServiceRequest\", \"Appointment\", \"HealthcareService\").\n - `id`: The logical ID of a specific FHIR resource instance.\n - `searchParam`: A mapping of FHIR search parameter names to their desired values (e.g., {\"category\":\"laboratory\",\"issued:\"2025-05-01\"}).\n - `operation`: The name of a custom FHIR operation or extended query defined for the resource (e.g., \"$expand\").\n\n## Development & Testing\n\n### Installing Development Dependencies\n\nTo run tests and contribute to development, install the test dependencies:\n\n**Using pip:**\n```bash\n# Install project in development mode with test dependencies\npip install -e '.[test]'\n\n# Or install from requirements file\npip install -r requirements-dev.txt\n```\n\n**Using uv:**\n```bash\n# Install development dependencies\nuv sync --dev\n```\n\n### Running Tests\n\nThe project includes a comprehensive test suite covering all major functionality:\n\n```bash\n# Simple test runner\npython run_tests.py\n\n# Or direct pytest usage\nPYTHONPATH=src python -m pytest tests/ -v --cov=src/fhir_mcp_server\n```\n**Using pytest:**\n```bash\npytest tests/\n```\nThis will discover and run all tests in the `tests/` directory.\n\n\n**Test Features:**\n- **100+ tests** with comprehensive coverage\n- **Full async/await support** using pytest-asyncio\n- **Complete mocking** of HTTP requests and external dependencies\n- **Coverage reporting** with terminal and HTML output\n- **Fast execution** with no real network calls\n\nThe test suite includes:\n- **Unit tests**: Core functionality testing\n- **Integration tests**: Component interaction validation\n- **Edge case coverage**: Error handling and validation scenarios\n- **Mocked OAuth flows**: Realistic authentication testing\n\nCoverage reports are generated in `htmlcov/index.html` for detailed analysis.\n",
"bugtrack_url": null,
"license": null,
"summary": "A Model Context Protocol (MCP) server that provides seamless, standardized access to Fast Healthcare Interoperability Resources (FHIR) data from any compatible FHIR server. Designed for easy integration with AI tools, developer workflows, and healthcare applications, it enables natural language and programmatic search, retrieval, and analysis of clinical data.",
"version": "0.9.0",
"project_urls": {
"Bug Tracker": "https://github.com/wso2/fhir-mcp-server/issues",
"Documentation": "https://github.com/wso2/fhir-mcp-server/blob/main/README.md",
"Homepage": "https://github.com/wso2/fhir-mcp-server"
},
"split_keywords": [
"fhir",
" healthcare",
" llm",
" mcp",
" model-context-protocol",
" modelcontextprotocol"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "c7c3cd54f66fcdb5ad2f8a9c9788b80475d44461e4849d4c9ff8baba8245eeb4",
"md5": "1e99738225d82db0112eb1aa2ee28d51",
"sha256": "58225475c419be8fdb440a449c94a4e696b364891bcf3dd5f0b993a6b9767740"
},
"downloads": -1,
"filename": "fhir_mcp_server-0.9.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1e99738225d82db0112eb1aa2ee28d51",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 28539,
"upload_time": "2025-07-22T18:40:17",
"upload_time_iso_8601": "2025-07-22T18:40:17.065700Z",
"url": "https://files.pythonhosted.org/packages/c7/c3/cd54f66fcdb5ad2f8a9c9788b80475d44461e4849d4c9ff8baba8245eeb4/fhir_mcp_server-0.9.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "4273b6d52d628a46c6d5f1e5daaf0d7a306dab1a95967b4c574244931081d941",
"md5": "259e2fa65695884ddf62a5d976a4558a",
"sha256": "7040e4397d50416f7a39c344cee586376e597fba4b919e62930c251725f0f054"
},
"downloads": -1,
"filename": "fhir_mcp_server-0.9.0.tar.gz",
"has_sig": false,
"md5_digest": "259e2fa65695884ddf62a5d976a4558a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 26213492,
"upload_time": "2025-07-22T18:40:19",
"upload_time_iso_8601": "2025-07-22T18:40:19.402969Z",
"url": "https://files.pythonhosted.org/packages/42/73/b6d52d628a46c6d5f1e5daaf0d7a306dab1a95967b4c574244931081d941/fhir_mcp_server-0.9.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-22 18:40:19",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "wso2",
"github_project": "fhir-mcp-server",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "aiohappyeyeballs",
"specs": [
[
"==",
"2.6.1"
]
]
},
{
"name": "aiohttp",
"specs": [
[
"==",
"3.12.2"
]
]
},
{
"name": "aiosignal",
"specs": [
[
"==",
"1.3.2"
]
]
},
{
"name": "annotated-types",
"specs": [
[
"==",
"0.7.0"
]
]
},
{
"name": "anyio",
"specs": [
[
"==",
"4.9.0"
]
]
},
{
"name": "attrs",
"specs": [
[
"==",
"25.3.0"
]
]
},
{
"name": "certifi",
"specs": [
[
"==",
"2025.4.26"
]
]
},
{
"name": "charset-normalizer",
"specs": [
[
"==",
"3.4.2"
]
]
},
{
"name": "click",
"specs": [
[
"==",
"8.2.1"
]
]
},
{
"name": "fhirpy",
"specs": [
[
"==",
"2.0.15"
]
]
},
{
"name": "frozenlist",
"specs": [
[
"==",
"1.6.0"
]
]
},
{
"name": "h11",
"specs": [
[
"==",
"0.16.0"
]
]
},
{
"name": "httpcore",
"specs": [
[
"==",
"1.0.9"
]
]
},
{
"name": "httpx",
"specs": [
[
"==",
"0.28.1"
]
]
},
{
"name": "httpx-sse",
"specs": [
[
"==",
"0.4.0"
]
]
},
{
"name": "idna",
"specs": [
[
"==",
"3.10"
]
]
},
{
"name": "markdown-it-py",
"specs": [
[
"==",
"3.0.0"
]
]
},
{
"name": "mcp",
"specs": [
[
"==",
"1.9.1"
]
]
},
{
"name": "mdurl",
"specs": [
[
"==",
"0.1.2"
]
]
},
{
"name": "multidict",
"specs": [
[
"==",
"6.4.4"
]
]
},
{
"name": "propcache",
"specs": [
[
"==",
"0.3.1"
]
]
},
{
"name": "pydantic",
"specs": [
[
"==",
"2.11.5"
]
]
},
{
"name": "pydantic-core",
"specs": [
[
"==",
"2.33.2"
]
]
},
{
"name": "pydantic-settings",
"specs": [
[
"==",
"2.9.1"
]
]
},
{
"name": "pygments",
"specs": [
[
"==",
"2.19.1"
]
]
},
{
"name": "python-dotenv",
"specs": [
[
"==",
"1.1.0"
]
]
},
{
"name": "python-multipart",
"specs": [
[
"==",
"0.0.20"
]
]
},
{
"name": "pytz",
"specs": [
[
"==",
"2025.2"
]
]
},
{
"name": "requests",
"specs": [
[
"==",
"2.32.3"
]
]
},
{
"name": "rich",
"specs": [
[
"==",
"14.0.0"
]
]
},
{
"name": "shellingham",
"specs": [
[
"==",
"1.5.4"
]
]
},
{
"name": "sniffio",
"specs": [
[
"==",
"1.3.1"
]
]
},
{
"name": "sse-starlette",
"specs": [
[
"==",
"2.3.5"
]
]
},
{
"name": "starlette",
"specs": [
[
"==",
"0.46.2"
]
]
},
{
"name": "typer",
"specs": [
[
"==",
"0.16.0"
]
]
},
{
"name": "typing-extensions",
"specs": [
[
"==",
"4.13.2"
]
]
},
{
"name": "typing-inspection",
"specs": [
[
"==",
"0.4.1"
]
]
},
{
"name": "urllib3",
"specs": [
[
"==",
"2.4.0"
]
]
},
{
"name": "uvicorn",
"specs": [
[
"==",
"0.34.2"
]
]
},
{
"name": "yarl",
"specs": [
[
"==",
"1.20.0"
]
]
}
],
"lcname": "fhir-mcp-server"
}
JSON
