Azure AHDS FHIR MCP Server 🚀

A Model Context Protocol (MCP) server implementation for Azure Health Data Services FHIR (Fast Healthcare Interoperability Resources). This service provides a standardized interface for interacting with Azure FHIR servers, enabling healthcare data operations through MCP tools.

Setup 🛠️

Installation 📦

Requires Python 3.13 or higher and `uv`.

Install uv first.

Configuration ⚙️

See the FastMCP guidance on `mcp.json` here: https://gofastmcp.com/integrations/mcp-json-configuration

Client Credentials Flow (default):

• Used for service-to-service authentication
• Leave `USE_FAST_MCP_OAUTH_PROXY=false`
• Keep `HTTP_TRANSPORT=false` to use stdio transport
• Uses Azure AD client credentials flow

{
    "mcpServers": {
        "fhir": {
            "type": "stdio",
            "command": "uvx",
            "args": [
                "azure-fhir-mcp-server"
            ],
            "env": {
                "fhirUrl": "https://your-fhir-server.azurehealthcareapis.com/fhir",
                "clientId": "your-client-id",
                "clientSecret": "your-client-secret",
                "tenantId": "your-tenant-id"
            }
        }
    }
}

OAuth On-Behalf-Of Flow:

Create the Azure App Registration

The OAuth on-behalf-of flow requires a confidential Azure AD application that represents the MCP server.

1. In the Azure portal, go to Microsoft Entra ID ➜ App registrations ➜ New registration. Give it a descriptive name such as `FHIR-MCP-Server`, set Supported account types to *Single tenant*, and leave the redirect URI unset for now.

2. After the app is created, capture the generated `Application (client) ID` and `Directory (tenant) ID` for later use.

3. Under Expose an API, select Set for the Application ID URI and accept the suggested value `api://{appId}`. Add a scope named `user_impersonation` with admin consent display/description also set to `user_impersonation`.

4. Under Certificates & secrets, create a New client secret (for example `FHIR-MCP-Secret-New`). Copy the secret value immediately; it is required for the MCP server `clientSecret` setting.

5. Under Authentication, add the following Web redirect URIs to support the FastMCP OAuth proxy:

Ensure Default client type remains *No* so the app stays confidential.

6. Under API permissions, choose Add a permission ➜ APIs my organization uses, search for your Azure Health Data Services FHIR server, and add the delegated scopes required for your scenario. Grant admin consent so the FastMCP proxy can request tokens without an interactive prompt.

• Environment variables:

• Start the MCP server with:

uv pip install -e .
uv run --env-file .env azure-fhir-mcp-server

• Update mcp.json:

{
    "mcpServers": {
        "fhir": {
            "type": "http",
            "url": "http://localhost:9002/mcp"
        }
    }
}

The following is a table of available environment configuration variables:

Available Tools 🔧

FHIR Resource Operations

• `search_fhir` - Search for FHIR resources based on a dictionary of search parameters
• `get_user_info` - (OAuth only) Returns information about the authenticated Azure user

Resource Access

The server provides access to all standard FHIR resources through the MCP resource protocol:

• `fhir://Patient/` - Access all Patient resources
• `fhir://Patient/{id}` - Access a specific Patient resource
• `fhir://Observation/` - Access all Observation resources
• `fhir://Observation/{id}` - Access a specific Observation resource
• `fhir://Medication/` - Access all Medication resources
• `fhir://Medication/{id}` - Access a specific Medication resource
• And many more...

Development 💻

Local Development Setup

1 - Clone the repository:

git clone https://github.com/erikhoward/azure-fhir-mcp-server.git
cd azure-fhir-mcp-server

2 - Create and activate virtual environment:

Linux/macOS:

python -m venv .venv
source .venv/bin/activate

Windows:

python -m venv .venv
.venv\Scripts\activate

3 - Install dependencies:

pip install -e ".[dev]"

4 - Copy and configure environment variables:

cp .env.example .env

Edit .env with your settings:

fhirUrl=https://your-fhir-server.azurehealthcareapis.com/fhir
clientId=your-client-id
clientSecret=your-client-secret
tenantId=your-tenant-id

5 - Claude Desktop Configuration

Open `claude_desktop_config.json` and add the following configuration.

On MacOs, the file is located here: `~/Library/Application Support/Claude Desktop/claude_desktop_config.json`.

On Windows, the file is located here: `%APPDATA%\Claude Desktop\claude_desktop_config.json`.

{
    "mcpServers": {
        "fhir": {
            "command": "uv",
            "args": [
                "--directory",
                "/path/to/azure-fhir-mcp-server/repo",
                "run",
                "azure_fhir_mcp_server"
            ],
            "env": {
                "LOG_LEVEL": "DEBUG",
                "fhirUrl": "https://your-fhir-server.azurehealthcareapis.com/fhir",
                "clientId": "your-client-id",
                "clientSecret": "your-client-secret",
                "tenantId": "your-tenant-id"
            }
        }
    }
}

6 - Restart Claude Desktop.

Running Tests

# Run all tests
python -m pytest tests/ -v

# Run with coverage
pytest tests/ --cov=src/azure_fhir_mcp_server

# Run specific test
pytest tests/test_fastmcp_metadata.py::TestFastMCPMetadata::test_fastmcp_server_discovery -v

# Run with detailed output
pytest tests/test_fastmcp_metadata.py::TestFastMCPMetadata::test_output_detailed_metadata -v -s

Contributions 🤝

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository

2. Create your feature branch (`git checkout -b feature/AmazingFeature`)

3. Commit your changes (`git commit -m '✨ Add some AmazingFeature'`)

4. Push to the branch (`git push origin feature/AmazingFeature`)

5. Open a Pull Request

License ⚖️

Licensed under MIT - see LICENSE.md file.

This is not an official Microsoft or Azure product.