# 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.
[](https://opensource.org/licenses/MIT) [](https://www.python.org/) [](https://github.com/modelcontextprotocol/spec)
## Setup 🛠️
### Installation 📦
Requires Python 3.13 or higher and `uv`.
Install [uv](https://docs.astral.sh/uv/getting-started/installation/) first.
### Configuration ⚙️
See the FastMCP guidance on `mcp.json` here: [https://gofastmcp.com/integrations/mcp-json-configuration](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
```json
{
"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:
- `http://localhost:9002/auth/callback`
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:
- Set `USE_FAST_MCP_OAUTH_PROXY=true`
- Requires `HTTP_TRANSPORT=true`
- Start the MCP server with:
```bash
uv pip install -e .
uv run --env-file .env azure-fhir-mcp-server
```
- Update mcp.json:
```json
{
"mcpServers": {
"fhir": {
"type": "http",
"url": "http://localhost:9002/mcp"
}
}
}
```
The following is a table of available environment configuration variables:
| Variable | Description | Default | Required |
|----------|-------------|---------|----------|
| `fhirUrl` | Azure FHIR server base URL (include `/fhir`) | - | Yes |
| `clientId` | Azure App registration client ID | - | Yes |
| `clientSecret` | Azure App registration client secret | - | Yes |
| `tenantId` | Azure AD tenant ID | - | Yes |
| `USE_FAST_MCP_OAUTH_PROXY` | Enable FastMCP Azure OAuth proxy integration | `false` | No |
| `HTTP_TRANSPORT` | Run the MCP server over HTTP transport (required for OAuth proxy) | `false` | No |
| `FASTMCP_HTTP_PORT` | Port exposed when `HTTP_TRANSPORT=true` | `9002` | No |
| `FHIR_SCOPE` | Override FHIR audience scope for the OBO flow (space-separated) | `{fhirUrl}/.default` | No |
| `FASTMCP_SERVER_AUTH_AZURE_BASE_URL` | Public base URL of your FastMCP server | `http://localhost:9002` | No |
| `FASTMCP_SERVER_AUTH_AZURE_REDIRECT_PATH` | OAuth callback path appended to the base URL | `/auth/callback` | No |
| `FASTMCP_SERVER_AUTH_AZURE_IDENTIFIER_URI` | Azure App registration Application ID URI | `api://{clientId}` | No |
| `FASTMCP_SERVER_AUTH_AZURE_REQUIRED_SCOPES` | Space-separated scopes requested by the Azure provider | `user_impersonation` | No |
| `FASTMCP_SERVER_AUTH_AZURE_ADDITIONAL_AUTHORIZE_SCOPES` | Optional space-separated scopes added to the authorize request | - | No |
| `LOG_LEVEL` | Logging level | `INFO` | No |
### 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:
```bash
git clone https://github.com/erikhoward/azure-fhir-mcp-server.git
cd azure-fhir-mcp-server
```
2 - Create and activate virtual environment:
Linux/macOS:
```bash
python -m venv .venv
source .venv/bin/activate
```
Windows:
```bash
python -m venv .venv
.venv\Scripts\activate
```
3 - Install dependencies:
```bash
pip install -e ".[dev]"
```
4 - Copy and configure environment variables:
```bash
cp .env.example .env
```
Edit .env with your settings:
```env
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`.
```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
```bash
# 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](LICENSE) file.
**This is not an official Microsoft or Azure product.**
Raw data
{
"_id": null,
"home_page": null,
"name": "azure-fhir-mcp-server",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.13",
"maintainer_email": null,
"keywords": "ahds, azure, fhir, healthcare, llm, mcp, model-context-protocol",
"author": null,
"author_email": "Erik Howard <erikhoward@pm.me>",
"download_url": "https://files.pythonhosted.org/packages/ee/8d/6aef4c5694c6ac6682b502e60e52068ab0cac04411939d9579d2a22e2f01/azure_fhir_mcp_server-1.2.0.tar.gz",
"platform": null,
"description": "# Azure AHDS FHIR MCP Server \ud83d\ude80\n\nA 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.\n\n[](https://opensource.org/licenses/MIT) [](https://www.python.org/) [](https://github.com/modelcontextprotocol/spec)\n\n## Setup \ud83d\udee0\ufe0f\n\n### Installation \ud83d\udce6\n\nRequires Python 3.13 or higher and `uv`.\n\nInstall [uv](https://docs.astral.sh/uv/getting-started/installation/) first.\n\n### Configuration \u2699\ufe0f\n\nSee the FastMCP guidance on `mcp.json` here: [https://gofastmcp.com/integrations/mcp-json-configuration](https://gofastmcp.com/integrations/mcp-json-configuration)\n\n#### Client Credentials Flow (default):\n\n- Used for service-to-service authentication\n- Leave `USE_FAST_MCP_OAUTH_PROXY=false`\n- Keep `HTTP_TRANSPORT=false` to use stdio transport\n- Uses Azure AD client credentials flow\n\n```json\n{\n \"mcpServers\": {\n \"fhir\": {\n \"type\": \"stdio\",\n \"command\": \"uvx\",\n \"args\": [\n \"azure-fhir-mcp-server\"\n ],\n \"env\": {\n \"fhirUrl\": \"https://your-fhir-server.azurehealthcareapis.com/fhir\",\n \"clientId\": \"your-client-id\",\n \"clientSecret\": \"your-client-secret\",\n \"tenantId\": \"your-tenant-id\"\n }\n }\n }\n}\n```\n\n#### OAuth On-Behalf-Of Flow:\n\n##### Create the Azure App Registration\n\nThe OAuth on-behalf-of flow requires a confidential Azure AD application that represents the MCP server.\n\n1. In the Azure portal, go to **Microsoft Entra ID \u279c App registrations \u279c 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.\n2. After the app is created, capture the generated `Application (client) ID` and `Directory (tenant) ID` for later use.\n3. 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`.\n4. 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.\n5. Under **Authentication**, add the following Web redirect URIs to support the FastMCP OAuth proxy:\n - `http://localhost:9002/auth/callback`\n Ensure **Default client type** remains *No* so the app stays confidential.\n6. Under **API permissions**, choose **Add a permission \u279c 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.\n\n- Environment variables:\n - Set `USE_FAST_MCP_OAUTH_PROXY=true`\n - Requires `HTTP_TRANSPORT=true`\n\n- Start the MCP server with:\n\n```bash\nuv pip install -e .\nuv run --env-file .env azure-fhir-mcp-server\n```\n\n- Update mcp.json:\n\n```json\n{\n \"mcpServers\": {\n \"fhir\": {\n \"type\": \"http\",\n \"url\": \"http://localhost:9002/mcp\"\n }\n }\n}\n```\n\nThe following is a table of available environment configuration variables:\n\n| Variable | Description | Default | Required |\n|----------|-------------|---------|----------|\n| `fhirUrl` | Azure FHIR server base URL (include `/fhir`) | - | Yes |\n| `clientId` | Azure App registration client ID | - | Yes |\n| `clientSecret` | Azure App registration client secret | - | Yes |\n| `tenantId` | Azure AD tenant ID | - | Yes |\n| `USE_FAST_MCP_OAUTH_PROXY` | Enable FastMCP Azure OAuth proxy integration | `false` | No |\n| `HTTP_TRANSPORT` | Run the MCP server over HTTP transport (required for OAuth proxy) | `false` | No |\n| `FASTMCP_HTTP_PORT` | Port exposed when `HTTP_TRANSPORT=true` | `9002` | No |\n| `FHIR_SCOPE` | Override FHIR audience scope for the OBO flow (space-separated) | `{fhirUrl}/.default` | No |\n| `FASTMCP_SERVER_AUTH_AZURE_BASE_URL` | Public base URL of your FastMCP server | `http://localhost:9002` | No |\n| `FASTMCP_SERVER_AUTH_AZURE_REDIRECT_PATH` | OAuth callback path appended to the base URL | `/auth/callback` | No |\n| `FASTMCP_SERVER_AUTH_AZURE_IDENTIFIER_URI` | Azure App registration Application ID URI | `api://{clientId}` | No |\n| `FASTMCP_SERVER_AUTH_AZURE_REQUIRED_SCOPES` | Space-separated scopes requested by the Azure provider | `user_impersonation` | No |\n| `FASTMCP_SERVER_AUTH_AZURE_ADDITIONAL_AUTHORIZE_SCOPES` | Optional space-separated scopes added to the authorize request | - | No |\n| `LOG_LEVEL` | Logging level | `INFO` | No |\n\n### Available Tools \ud83d\udd27\n\n#### FHIR Resource Operations\n\n* `search_fhir` - Search for FHIR resources based on a dictionary of search parameters\n* `get_user_info` - (OAuth only) Returns information about the authenticated Azure user\n\n#### Resource Access\n\nThe server provides access to all standard FHIR resources through the MCP resource protocol:\n\n* `fhir://Patient/` - Access all Patient resources\n* `fhir://Patient/{id}` - Access a specific Patient resource\n* `fhir://Observation/` - Access all Observation resources\n* `fhir://Observation/{id}` - Access a specific Observation resource\n* `fhir://Medication/` - Access all Medication resources\n* `fhir://Medication/{id}` - Access a specific Medication resource\n* And many more...\n\n## Development \ud83d\udcbb\n\n### Local Development Setup\n\n1 - Clone the repository:\n\n```bash\ngit clone https://github.com/erikhoward/azure-fhir-mcp-server.git\ncd azure-fhir-mcp-server\n```\n\n2 - Create and activate virtual environment:\n\nLinux/macOS:\n\n```bash\npython -m venv .venv\nsource .venv/bin/activate\n```\n\nWindows:\n\n```bash\npython -m venv .venv\n.venv\\Scripts\\activate\n```\n\n3 - Install dependencies:\n\n```bash\npip install -e \".[dev]\"\n```\n\n4 - Copy and configure environment variables:\n\n```bash\ncp .env.example .env\n```\n\nEdit .env with your settings:\n\n```env\nfhirUrl=https://your-fhir-server.azurehealthcareapis.com/fhir\nclientId=your-client-id\nclientSecret=your-client-secret\ntenantId=your-tenant-id\n```\n\n5 - Claude Desktop Configuration\n\nOpen `claude_desktop_config.json` and add the following configuration.\n\nOn MacOs, the file is located here: `~/Library/Application Support/Claude Desktop/claude_desktop_config.json`.\n\nOn Windows, the file is located here: `%APPDATA%\\Claude Desktop\\claude_desktop_config.json`.\n\n```json\n{\n \"mcpServers\": {\n \"fhir\": {\n \"command\": \"uv\",\n \"args\": [\n \"--directory\",\n \"/path/to/azure-fhir-mcp-server/repo\",\n \"run\",\n \"azure_fhir_mcp_server\"\n ],\n \"env\": {\n \"LOG_LEVEL\": \"DEBUG\",\n \"fhirUrl\": \"https://your-fhir-server.azurehealthcareapis.com/fhir\",\n \"clientId\": \"your-client-id\",\n \"clientSecret\": \"your-client-secret\",\n \"tenantId\": \"your-tenant-id\"\n }\n }\n }\n}\n```\n\n6 - Restart Claude Desktop.\n\n## Running Tests\n\n```bash\n# Run all tests\npython -m pytest tests/ -v\n\n# Run with coverage\npytest tests/ --cov=src/azure_fhir_mcp_server\n\n# Run specific test\npytest tests/test_fastmcp_metadata.py::TestFastMCPMetadata::test_fastmcp_server_discovery -v\n\n# Run with detailed output\npytest tests/test_fastmcp_metadata.py::TestFastMCPMetadata::test_output_detailed_metadata -v -s\n```\n\n## Contributions \ud83e\udd1d\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/AmazingFeature`)\n3. Commit your changes (`git commit -m '\u2728 Add some AmazingFeature'`)\n4. Push to the branch (`git push origin feature/AmazingFeature`)\n5. Open a Pull Request\n\n## License \u2696\ufe0f\n\nLicensed under MIT - see [LICENSE.md](LICENSE) file.\n\n**This is not an official Microsoft or Azure product.**\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Azure AHDS FHIR MCP Server",
"version": "1.2.0",
"project_urls": {
"Bug Tracker": "https://github.com/erikhoward/azure-fhir-mcp-server/issues",
"Documentation": "https://github.com/erikhoward/azure-fhir-mcp-server/tree/main#azure-fhir-mcp-server-",
"Homepage": "https://github.com/erikhoward/azure-fhir-mcp-server"
},
"split_keywords": [
"ahds",
" azure",
" fhir",
" healthcare",
" llm",
" mcp",
" model-context-protocol"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "985e576d7b1c3cd7dff4dd0567b35b4754e6d60be29225995fb6d19f8689d933",
"md5": "b94e07103846b63e3811b08abdf7eea4",
"sha256": "839d24ac5621c834cfb07dc7d0ad6486914d8043a90e858f0bd42ea155cee35a"
},
"downloads": -1,
"filename": "azure_fhir_mcp_server-1.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b94e07103846b63e3811b08abdf7eea4",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.13",
"size": 23724,
"upload_time": "2025-10-10T21:33:04",
"upload_time_iso_8601": "2025-10-10T21:33:04.608930Z",
"url": "https://files.pythonhosted.org/packages/98/5e/576d7b1c3cd7dff4dd0567b35b4754e6d60be29225995fb6d19f8689d933/azure_fhir_mcp_server-1.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "ee8d6aef4c5694c6ac6682b502e60e52068ab0cac04411939d9579d2a22e2f01",
"md5": "f04a8cb39b5ac18b1d9a5cda2cb7d7c2",
"sha256": "13d25ca4c5da4e586948798b4a076247acd9ea323803a3c7c453cd4a48d6010b"
},
"downloads": -1,
"filename": "azure_fhir_mcp_server-1.2.0.tar.gz",
"has_sig": false,
"md5_digest": "f04a8cb39b5ac18b1d9a5cda2cb7d7c2",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.13",
"size": 93234,
"upload_time": "2025-10-10T21:33:05",
"upload_time_iso_8601": "2025-10-10T21:33:05.667897Z",
"url": "https://files.pythonhosted.org/packages/ee/8d/6aef4c5694c6ac6682b502e60e52068ab0cac04411939d9579d2a22e2f01/azure_fhir_mcp_server-1.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-10 21:33:05",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "erikhoward",
"github_project": "azure-fhir-mcp-server",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "azure-fhir-mcp-server"
}
JSON
