FHIR MCP Server
A Model Context Protocol (MCP) server that provides secure, standardized access to FHIR (Fast Healthcare Interoperability Resources) servers. This server acts as a bridge between MCP clients and FHIR APIs, offering a simplified and secure way to access healthcare data.
Features
- MCP Protocol Support: Full Model Context Protocol implementation
- FHIR R4 Compatibility: Works with any FHIR R4-compliant server
- Simplified Configuration: Easy setup with environment variables
- Docker Ready: Containerized for easy deployment
- Health Monitoring: Built-in health check endpoints
- Security: Optional OAuth/Bearer token authentication
- Two Server Modes: Simple server for development, full server for production
Supported FHIR Operations
The server provides the following MCP tools for FHIR operations:
get_capabilities- Get FHIR server capabilities for a resource typesearch- Search for FHIR resources with parametersread- Read a specific FHIR resource by IDcreate- Create a new FHIR resourceupdate- Update an existing FHIR resourcedelete- Delete a FHIR resource
Quick Start
Using Docker Compose (Recommended)
- Clone the repository and navigate to the project root
- Copy the environment template:
cp env.template .env
- Edit
.envwith your FHIR server configuration - Start the server:
docker-compose up fhir-mcp-server
Manual Installation
-
Install dependencies:
pip install -r requirements.txt
-
Set environment variables:
export FHIR_MCP_FHIR__BASE_URL="https://hapi.fhir.org/baseR4" export FHIR_MCP_HOST="localhost" export FHIR_MCP_PORT="8004"
-
Run the server:
python -m fhir_mcp_server
Configuration
Environment Variables
| Variable | Description | Default |
|---|---|---|
FHIR_MCP_HOST |
Server host address | localhost |
FHIR_MCP_PORT |
Server port | 8004 |
FHIR_MCP_FHIR__BASE_URL |
FHIR server base URL | https://hapi.fhir.org/baseR4 |
FHIR_MCP_FHIR__ACCESS_TOKEN |
Bearer token for FHIR server | (empty) |
FHIR_MCP_FHIR__TIMEOUT |
Request timeout in seconds | 30 |
FHIR_MCP_USE_SIMPLE |
Use simplified server | true |
Server Modes
Simple Server (Default)
- Lightweight implementation
- Basic FHIR operations
- Minimal dependencies
- Best for development and testing
Full Server
- Complete OAuth2/OIDC support
- Advanced authentication flows
- Production-ready features
- Set
FHIR_MCP_USE_SIMPLE=falseto enable
Usage Examples
Using with Healthcare AI UI
The FHIR MCP server integrates seamlessly with the Healthcare AI UI:
- Enable MCP mode in UI Settings
- Set MCP server URL to
http://localhost:8004 - Configure your FHIR server URL
- Test the connection
Direct MCP Protocol Usage
// Example MCP request to search for patients
const request = {
jsonrpc: "2.0",
id: 1,
method: "tools/call",
params: {
name: "search",
arguments: {
type: "Patient",
searchParam: {
name: "John"
}
}
}
};
fetch('http://localhost:8004/mcp', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(request)
});
API Endpoints
POST /mcp- MCP protocol endpointGET /health- Health check endpointGET /oauth/callback- OAuth callback (full server only)GET /fhir/callback- FHIR OAuth callback (full server only)
Health Check
The server provides a health check endpoint at /health:
curl http://localhost:8004/health
Response:
{
"status": "healthy",
"service": "FHIR MCP Server",
"version": "1.0.0",
"fhir_url": "https://hapi.fhir.org/baseR4"
}
Development
Running Tests
# Install test dependencies
pip install pytest pytest-asyncio
# Run tests
pytest tests/
Code Structure
fhir_mcp_server/
├── Dockerfile # Docker configuration for the service
├── README.md # This README file
├── __init__.py # Package initialization
├── __main__.py # Main entry point for the service
├── fhir_mcp_service.py # Main FHIR MCP service implementing business logic and tool definitions
└── requirements.txt # Python dependencies
Security Considerations
- Always use HTTPS in production
- Configure proper FHIR server authentication
- Validate all input parameters
- Monitor access logs
- Keep dependencies updated
Troubleshooting
Common Issues
-
Connection Refused
- Check if the server is running
- Verify host and port configuration
- Ensure firewall allows connections
-
FHIR Authentication Errors
- Verify FHIR server URL is correct
- Check access token if using authentication
- Ensure FHIR server is accessible
-
MCP Protocol Errors
- Verify JSON-RPC 2.0 format
- Check method and parameter names
- Review server logs for details
Logs
Enable debug logging for troubleshooting:
python -m fhir_mcp_server --log-level DEBUG
Contributing
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests
- Submit a pull request
License
This project is licensed under the MIT License. See LICENSE file for details.
Support
For support and questions:
- Open an issue on GitHub
- Check the documentation
- Review the troubleshooting guide
Related Projects
- Healthcare AI Agents - Main healthcare AI platform
- FHIR Proxy - Alternative FHIR access method
- MCP Specification - Official MCP documentation
New File Structure
fhir_mcp_server/
├── Dockerfile # Docker configuration for the service
├── README.md # This README file
├── __init__.py # Package initialization
├── __main__.py # Main entry point for the service
├── fhir_mcp_service.py # Main FHIR MCP service implementing business logic and tool definitions
└── requirements.txt # Python dependencies
Metadata
Release files for iflow-mcp_amitpuri-fhir-mcp-server 1.0.3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| iflow_mcp_amitpuri_fhir_mcp_server-1.0.3.tar.gz | 22.5 kB | Without provenance | Details for iflow_mcp_amitpuri_fhir_mcp_server-1.0.3.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| iflow_mcp_amitpuri_fhir_mcp_server-1.0.3-py3-none-any.whl | Python 3 | none | any | Details for iflow_mcp_amitpuri_fhir_mcp_server-1.0.3-py3-none-any.whl |
Total release size: 39.4 kB
Release files / iflow_mcp_amitpuri_fhir_mcp_server-1.0.3.tar.gz
| Download URL | iflow_mcp_amitpuri_fhir_mcp_server-1.0.3.tar.gz |
|---|---|
| Size | 22.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
822ea011b277f56aa227a0658fa5852c4908f1cc8c7df8e4671bb22db5363b76
|
|
BLAKE2b-256 checksum How to use checksums |
261250ed9dbeda217ddfec277fb57f5872b232fc650f33fc3ab287bde284bc17
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.10.2 {"installer":{"name":"uv","version":"0.10.2","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"13","id":"trixie","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / iflow_mcp_amitpuri_fhir_mcp_server-1.0.3-py3-none-any.whl
| Download URL | iflow_mcp_amitpuri_fhir_mcp_server-1.0.3-py3-none-any.whl |
|---|---|
| Size | 16.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
42c50cdca13bf223d1e9f987ad17bff21b8408c4b33ef22cd3e6eca95b01c8a2
|
|
BLAKE2b-256 checksum How to use checksums |
88e4f67578dbbf61fd1bb6317196eb13483960f4b0d87e94f3f07766d923b6da
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.10.2 {"installer":{"name":"uv","version":"0.10.2","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"13","id":"trixie","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for iflow-mcp_amitpuri-fhir-mcp-server 1.0.3
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.