Used for high-performance asynchronous HTTP operations, enabling non-blocking I/O for FHIR server communications
Manages environment variables for configuration, particularly for storing the OpenAI API key and FHIR server credentials
Provides architecture diagram visualization capabilities for representing the FHIR system components and relationships
Enables AI-powered clinical text analysis, code mapping, and patient matching features for enhanced healthcare data processing
Core runtime environment for the FHIR server implementation and tools library
Provides enhanced terminal output formatting for the FHIR Timeline Agent's interactive CLI interface
FHIR Careplan - Universal FHIR Server and Tools
A comprehensive FHIR (Fast Healthcare Interoperability Resources) server and toolkit designed for healthcare data integration, patient care planning, and clinical decision support. This project provides a universal interface to multiple FHIR servers with advanced AI-powered clinical analysis capabilities.
🏥 Overview
The FHIR Careplan project consists of two main components:
Universal FHIR MCP Server (
fhir_server.py
) - A Model Context Protocol (MCP) server that provides standardized access to multiple FHIR serversFHIR Tools Library (
fhir_tools.py
) - A comprehensive Python library for FHIR data manipulation, analysis, and AI-powered clinical insights
✨ Key Features
🔗 Multi-Server FHIR Integration
Universal FHIR Interface: Connect to multiple FHIR servers (Epic, Cerner, HAPI, Firely, etc.)
Vendor-Agnostic: Standardized API regardless of underlying FHIR server implementation
Real-time Connectivity Testing: Automatic server health checks and diagnostics
Intelligent Failover: Automatic switching between servers for optimal performance
🤖 AI-Powered Clinical Analysis
OpenAI Integration: Extract clinical keywords and concepts from free text
Semantic Mapping: Map clinical terms to standardized FHIR codes
Similar Patient Matching: Find patients with similar clinical profiles
Predictive Analytics: Generate care recommendations based on historical data
📊 Comprehensive Patient Data Access
Complete Patient Records: Demographics, conditions, medications, procedures, encounters
Vital Signs & Lab Results: Categorized observations with time-series data
Care Plans & Teams: Treatment plans and healthcare provider information
Allergies & Procedures: Complete medical history tracking
🚀 Performance Optimization
Async Operations: Non-blocking I/O for high-performance data access
Intelligent Caching: Condition codes and frequently accessed data caching
Batch Processing: Efficient handling of multiple patient records
Connection Pooling: Optimized HTTP connections for multiple servers
🛠 Installation
Prerequisites
Python 3.11 or higher
OpenAI API key (for AI features)
Access to FHIR servers (local or remote)
Setting Up MCP Server
Clone the Repository
git clone https://github.com/Kushagra-Dutta/Fhir-MCP.git cd FHIR-MCPInstall Dependencies
pip install -r requirements.txt # or using uv uv syncConfigure Environment Variables
# Create .env file echo "OPENAI_API_KEY=your_openai_api_key" > .envRun the FHIR MCP Server
python fhir_server.py
Setting Up Firely Test Database Locally
Obtain a Firely Server License Key
Visit Firely Server Trial Page
Fill out the form to receive a license key via email
You'll receive the license key and download files (license valid for 7 days)
Save the license file as
firelyserver-license.json
Set Up Using Docker
# Pull the Firely server image docker pull firely/server # Run the container # For Windows CMD: docker run -d -p 9090:4080 --name firely.server -v %CD%/firelyserver-license.json:/app/firelyserver-license.json firely/server # For PowerShell or macOS/Linux: docker run -d -p 9090:4080 --name firely.server -v ${PWD}/firelyserver-license.json:/app/firelyserver-license.json firely/server # Verify container is running docker psLoad Test Data
Use Postman to load test data bundles
Create a new PUT request in Postman
Set request type to raw JSON
Copy content from test data bundles
Send requests to base URL (http://localhost:9090)
Repeat for each data bundle
After completing these steps, you'll have a working test database accessible at http://localhost:9090.
Setting Up MCP Chatbot Client
You can set up the MCP chatbot client either by forking the repository or using Docker. The chatbot will serve as the frontend interface for interacting with the FHIR server.
Get the Chatbot setup
# Clone the repository git clone https://github.com/cgoinglove/mcp-client-chatbot.git cd mcp-client-chatbotInstall PNPM (if not installed)
npm install -g pnpmChoose Setup Method:
Docker Compose Setup 🐳
# Install dependencies pnpm i # Configure environment variables # Edit .env file with your API keys (created automatically after pnpm i) # Start all services including PostgreSQL pnpm docker-compose:upLocal Setup 🚀
# Install dependencies pnpm i # Setup environment variables pnpm initial:env # Start PostgreSQL (skip if already running) pnpm docker:pg # Run database migrations pnpm db:migrate # Start development server pnpm dev # Optional: Build & start for production-like testing pnpm build:local && pnpm startConfigure Environment Variables Create/edit
.env
file with required API keys:# LLM Provider API Keys (add the ones you plan to use) OPENAI_API_KEY=**** GOOGLE_GENERATIVE_AI_API_KEY=**** ANTHROPIC_API_KEY=**** XAI_API_KEY=**** OPENROUTER_API_KEY=**** OLLAMA_BASE_URL=http://localhost:11434/api # Auth Configuration BETTER_AUTH_SECRET=**** # Generate with: npx @better-auth/cli@latest secret BETTER_AUTH_URL= # Optional: URL you access the app from # Database Configuration POSTGRES_URL=postgres://your_username:your_password@localhost:5432/your_database_name # MCP Configuration FILE_BASED_MCP_CONFIG=false # Optional OAuth Settings (for Google/GitHub login) GOOGLE_CLIENT_ID= GOOGLE_CLIENT_SECRET= GITHUB_CLIENT_ID= GITHUB_CLIENT_SECRET=Connect MCP Server to Chatbot
Access the chatbot at http://localhost:3000
Create an account and login
Go to MCP configuration
Click "Add Server"
Copy-paste your
.chatbot-config.json
configuration
Configure System Prompt
Navigate to
src/app/prompts.ts
in the chatbot repositoryReplace the default system prompt with your custom prompt from
system_prompt.txt
Example system prompt structure:
export const defaultSystemPrompt = `You are a powerful agentic AI coding assistant. You have access to a set of tools you can use to answer the user's question. <communication> 1. Be conversational but professional. 2. Refer to the USER in the second person and yourself in the first person. 3. Format your responses in markdown. 4. NEVER lie or make things up. </communication> <tool_calling> Follow these rules regarding tool calls: 1. ALWAYS follow the tool call schema exactly as specified. 2. NEVER call tools that are not explicitly provided. 3. Only calls tools when they are necessary. 4. Before calling each tool, first explain to the USER why you are calling it. </tool_calling> <making_code_changes> When making code changes: 1. Add all necessary import statements and dependencies 2. NEVER output code to the USER, unless requested 3. Use appropriate code edit tools for implementation </making_code_changes> `;Customize the prompt sections based on your needs:
<communication>
: Define how the AI should interact<tool_calling>
: Specify rules for using tools<making_code_changes>
: Set guidelines for code modifications
Save the changes and restart the development server
After completing these steps, your chatbot will be connected to the MCP server and ready to interact with the FHIR database.
🏗 Architecture
Core Components
Server Registry
The system maintains a comprehensive registry of FHIR servers:
Firely Local (
http://localhost:9090
) - Local development serverHAPI R4 (
http://hapi.fhir.org/baseR4
) - Public test serverEpic, Cerner, Azure - Enterprise healthcare systems (configurable)
📖 Usage Guide
Basic FHIR Operations
1. Server Management
2. Patient Search
3. Patient Data Retrieval
AI-Powered Clinical Analysis
1. Clinical Text Extraction
2. FHIR Code Mapping
3. Similar Patient Matching
MCP Server Integration
The FHIR server can be used as an MCP server for integration with AI assistants:
🔧 Configuration
Server Configuration
The system supports multiple FHIR servers configured in fhir_tools.py
:
Environment Variables
🔍 Available Tools
Core FHIR Operations
switch_server(server_name)
- Switch between FHIR serverstest_server_connectivity(server_name)
- Test server connectivityfind_patient(search_criteria)
- Search for patientsget_comprehensive_patient_info(patient_id)
- Get complete patient data
Clinical Data Access
get_patient_observations(patient_id)
- Get patient observationsget_patient_conditions(patient_id)
- Get patient conditionsget_patient_medications(patient_id)
- Get patient medicationsget_vital_signs(patient_id)
- Get vital signsget_lab_results(patient_id)
- Get laboratory resultsget_patient_encounters(patient_id)
- Get patient encountersget_patient_allergies(patient_id)
- Get patient allergiesget_patient_procedures(patient_id)
- Get patient procedures
AI-Powered Analysis
extract_clinical_keywords(text)
- Extract clinical information from textmap_to_fhir_codes_fast(clinical_data)
- Map terms to FHIR codesfind_similar_patients_simple(criteria)
- Find similar patientsextract_condition_codes_from_fhir()
- Extract all condition codes
System Management
list_available_servers()
- List all configured serversget_server_registry()
- Get complete server registrydiagnose_fhir_server(server_name)
- Diagnose server capabilitiesclear_condition_cache()
- Clear condition codes cacheget_condition_cache_stats()
- Get cache performance statistics
🧪 Testing Tools
MCP Inspector
The MCP (Model Context Protocol) Inspector is a powerful development and testing tool that helps debug and validate FHIR server interactions. It provides real-time inspection of server behavior and API responses.
Using MCP Inspector
Features
Real-time Monitoring: Watch FHIR server interactions as they happen
Request/Response Logging: Detailed logs of all API calls and responses
Error Detection: Immediate feedback on API errors or misconfigurations
Performance Metrics: Track response times and server performance
Debug Mode: Enhanced logging for development troubleshooting
Log File Location
The inspector writes detailed logs to:
Best Practices
Use MCP Inspector during development to validate server behavior
Monitor the log file for unexpected errors or performance issues
Run the inspector when implementing new FHIR endpoints
Use it to debug connection issues with external FHIR servers
🏥 Business Applications
Hospital Engagement Platform
This toolkit can power automated hospital engagement platforms:
Patient Care Coordination
Automated care plan generation
Treatment timeline management
Multi-disciplinary team coordination
Clinical Decision Support
Evidence-based treatment recommendations
Risk assessment and early warnings
Outcome prediction based on similar cases
Resource Optimization
Predictive analytics for resource allocation
Automated scheduling and capacity management
Cost optimization through data-driven insights
Quality Improvement
Automated quality metrics tracking
Compliance monitoring and reporting
Performance analytics and benchmarking
🔐 Security & Compliance
HIPAA Compliance: Designed with healthcare data privacy in mind
Secure Communication: HTTPS/TLS encryption for all server communications
Authentication Support: Multiple authentication methods (OAuth, API keys, etc.)
Audit Logging: Comprehensive logging for compliance and debugging
📊 Performance Features
Async Operations: Non-blocking I/O for high throughput
Connection Pooling: Efficient HTTP connection management
Intelligent Caching: Condition codes and metadata caching
Batch Processing: Efficient handling of multiple records
Error Handling: Robust error handling and retry mechanisms
🧪 Testing
Running Tests
Server Diagnostics
📝 Logging
The system provides comprehensive logging:
🤝 Contributing
Fork the repository
Create a feature branch
Make your changes
Add tests for new functionality
Submit a pull request
📄 License
This project is licensed under the MIT License - see the LICENSE file for details.
🆘 Support
For support and questions:
Create an issue in the GitHub repository
Check the logs directory for detailed error information
Use the diagnostic tools for server troubleshooting
🔄 Version History
v0.1.0 - Initial release with core FHIR functionality
v0.2.0 - Added AI-powered clinical analysis
v0.3.0 - Enhanced multi-server support and caching
🎯 Roadmap
Advanced analytics dashboard
Real-time data streaming
Machine learning model integration
Enhanced security features
Mobile application support
Cloud deployment templates
🕒 FHIR Timeline Agent
The FHIR Timeline Agent (fhir_timeline_agent.py
) is a specialized agent designed to generate detailed clinical treatment timelines from patient queries using real FHIR data. It's specifically configured to work with the Firely Local FHIR server.
Features
Natural Language Processing: Converts free-text patient queries into structured clinical data
Real Patient Data Analysis: Uses actual FHIR patient records for timeline generation
AI-Powered Timeline Generation: Leverages OpenAI GPT-4 for accurate clinical timelines
Interactive CLI Interface: User-friendly command-line interface with rich formatting
Comprehensive Patient Matching: Finds similar patients based on age, gender, and conditions
Usage
Example Queries
Timeline Generation Process
Query Processing
Extracts clinical keywords from natural language
Identifies age, gender, conditions, stage, and biomarkers
FHIR Code Mapping
Maps clinical terms to standardized FHIR codes
Uses Firely Local server's code systems
Similar Patient Search
Finds matching patients in the FHIR database
Scores matches based on age, gender, and conditions
Data Aggregation
Collects comprehensive medical history
Includes procedures, medications, encounters
Timeline Generation
Creates detailed treatment timeline using AI
Organizes events chronologically with clinical context
Output Format
The agent generates rich, formatted output including:
Patient Profile: Demographics, diagnosis, stage, biomarkers
Treatment Timeline: Step-by-step clinical events with dates
Clinical Outcomes: Treatment response, survival status, toxicity
Data Sources: Server information and analysis metrics
Configuration
The agent is hardcoded to use:
Firely Local FHIR server (
http://localhost:9090
)OpenAI GPT-4 for timeline generation
Rich console output for formatted display
Requirements
OpenAI API key (set in
.env
file)Running Firely Local FHIR server
Python packages:
openai>=1.86.0 rich>=13.7.0 python-dotenv>=1.0.0 aiohttp>=3.8.0
Best Practices
Provide complete patient information in queries
Include age, gender, and primary diagnosis
Add stage and biomarker information when available
Use specific clinical terms for better matching
Error Handling
The agent includes robust error handling for:
Missing patient information
FHIR server connectivity issues
AI generation failures
Data parsing errors
Each error is displayed with helpful suggestions for resolution.
Built with ❤️ for healthcare interoperability and patient care improvement
This server cannot be installed
hybrid server
The server is able to function both locally and remotely, depending on the configuration or use case.
A comprehensive Model Context Protocol server that provides universal access to multiple FHIR servers with AI-powered clinical analysis capabilities for healthcare data integration and patient care planning.
- 🏥 Overview
- ✨ Key Features
- 🛠 Installation
- 🏗 Architecture
- 📖 Usage Guide
- 🔧 Configuration
- 🔍 Available Tools
- 🧪 Testing Tools
- 🏥 Business Applications
- 🔐 Security & Compliance
- 📊 Performance Features
- 🧪 Testing
- 📝 Logging
- 🤝 Contributing
- 📄 License
- 🆘 Support
- 🔄 Version History
- 🎯 Roadmap
- 🕒 FHIR Timeline Agent
- Built with ❤️ for healthcare interoperability and patient care improvement
Related MCP Servers
- AsecurityAlicenseAqualityA Model Context Protocol server providing AI assistants with access to healthcare data tools, including FDA drug information, PubMed research, health topics, clinical trials, and medical terminology lookup.Last updated -71348MIT License
- -securityAlicense-qualityA Model Context Protocol server that connects AI tools to Electronic Health Records using SMART on FHIR, allowing secure searching, querying, and analysis of patient data from compatible EHRs.Last updated -63MIT License
- -securityAlicense-qualityA server that implements the Model Context Protocol, providing a standardized way to connect AI models to different data sources and tools.Last updated -010MIT License
- AsecurityAlicenseAqualityA Model Context Protocol server that enables standardized interaction with Azure Health Data Services FHIR servers, allowing healthcare data operations through MCP tools.Last updated -113MIT License