sp2learn/medical-mcp-server

🏥 Intelligent Medical Assistant

A comprehensive Patient-Centric Medical Intelligence System that combines MCP (Model Context Protocol) server capabilities with an intelligent web interface. This system provides natural language medical queries, patient data analysis, and professional medical insights powered by Gemini AI.

✨ Key Features

🤖 Intelligent Medical Assistant

• Natural Language Processing - Ask questions like "What is Ben's sleep summary?"
• Automatic Tool Routing - AI decides which patient data to access
• Conversational Interface - Single input for all medical queries
• Professional Medical Responses - Evidence-based information with disclaimers

👥 Patient Data Management

• Real Patient Data - CSV-based patient records and biometrics
• Comprehensive Tracking - Sleep patterns, vital signs, lab results, medications
• Trend Analysis - Historical data analysis and insights
• Multi-Patient Support - Manage multiple patient records

🔧 Dual Architecture

• MCP Server - Integration with Kiro IDE and other MCP clients
• Web Application - Professional web interface with authentication
• RESTful API - Programmatic access to medical data and insights

📊 Available Patient Data

• Ben Smith (34M) - Hypertension, Type 2 Diabetes
  • 15 days of detailed sleep data (duration, quality, efficiency)
  • Vital signs tracking (BP, heart rate, glucose, weight)
• Sarah Jones (28F) - Asthma
• Mike Wilson (45M) - High Cholesterol

🚀 Quick Start

1. Installation

# Clone and setup
git clone https://github.com/sp2learn/medical-mcp-server.git
cd medical-mcp-server

# Create virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

2. Configuration

# Copy environment template
cp .env.example .env

# Edit .env with your API keys
MEDICAL_MODEL=gemini
GOOGLE_API_KEY=your_gemini_api_key_here
DISPLAY_TIMEZONE=America/New_York

3. Run the System

Web Application:

python web_app.py
# Visit: http://localhost:8000
# Login: demo/password, doctor/secret123, admin/admin2024

MCP Server:

python server.py
# For integration with Kiro IDE or other MCP clients

🎯 Usage Examples

Natural Language Queries

The intelligent assistant understands natural language and automatically routes to appropriate tools:

🩺 "What is Ben's sleep summary for the past week?"
→ Analyzes sleep data, provides trends and insights

📊 "Show me Ben's blood pressure trends"
→ Reviews vital signs, identifies patterns

💊 "What medications is Ben taking?"
→ Lists current medications and adherence data

🔍 "What are the symptoms of diabetes?"
→ Provides general medical information

📈 "Compare Ben's glucose levels over time"
→ Analyzes lab data and trends

MCP Integration

Add to your Kiro IDE configuration (.kiro/settings/mcp.json):

{
  "mcpServers": {
    "medical-query": {
      "command": "/path/to/medical-mcp-server/venv/bin/python",
      "args": ["/path/to/medical-mcp-server/server.py"],
      "disabled": false,
      "autoApprove": [
        "medical_query",
        "symptom_checker", 
        "get_patient_sleep_pattern",
        "get_patient_vitals",
        "get_patient_labs",
        "get_medication_adherence",
        "get_patient_activity",
        "get_patient_overview"
      ]
    }
  }
}

🛠️ Available Tools

MCP Tools (8 total)

Tool Management

# List all tools and their status
python manage_tools.py list

# Show detailed tool information  
python manage_tools.py details get_patient_sleep_pattern

# Enable/disable tools
python manage_tools.py enable medical_query
python manage_tools.py disable symptom_checker

📁 Project Structure

medical-mcp-server/
├── 🤖 Core Intelligence
│   ├── intelligent_medical_assistant.py  # Natural language processing
│   ├── medical_client.py                 # AI model integration
│   └── patient_data_manager.py           # Patient data management
├── 🌐 Web Interface  
│   ├── web_app.py                        # FastAPI web application
│   ├── templates/                        # HTML templates
│   │   ├── dashboard.html                # Main interface
│   │   ├── login.html                    # Authentication
│   │   └── base.html                     # Base template
│   └── static/                           # CSS, JavaScript, assets
├── 🔧 MCP Server
│   ├── server.py                         # MCP protocol server
│   ├── tool_config.py                    # Centralized tool configuration
│   └── manage_tools.py                   # Tool management CLI
├── 📊 Patient Data
│   └── data/
│       ├── patients.csv                  # Patient demographics
│       ├── ben_sleep_data.csv            # Ben's sleep metrics
│       └── ben_vitals_data.csv           # Ben's vital signs
└── 🚀 Deployment
    ├── Dockerfile                        # Container configuration
    ├── docker-compose.yml                # Multi-service setup
    └── render.yaml                       # Render deployment config

🌐 Deployment

Local Development

source venv/bin/activate
python web_app.py
# Access: http://localhost:8000

Cloud Deployment (Render)

1. Push to GitHub
2. Connect repository to Render
3. Set environment variables:
   • MEDICAL_MODEL=gemini
   • GOOGLE_API_KEY=your_key
4. Deploy automatically

Docker Deployment

# Build and run with Docker Compose
docker-compose up --build

# Or build manually
docker build -t medical-mcp-server .
docker run -p 8000:8000 --env-file .env medical-mcp-server

🔐 Authentication & Security

Web Interface

• Session-based authentication with secure cookies
• Role-based access (demo, doctor, admin accounts)
• 24-hour session expiration
• HTTPS ready for production deployment

Demo Accounts

📈 Patient Data Format

Patient Demographics (patients.csv)

patient_id,first_name,last_name,age,gender,conditions,medications,last_visit
ben_smith,Ben,Smith,34,male,"hypertension,type_2_diabetes","metformin,lisinopril",2024-01-15

Sleep Data (ben_sleep_data.csv)

date,sleep_hours,bedtime,wake_time,sleep_quality,deep_sleep_minutes,rem_sleep_minutes
2024-09-14,7.2,22:30,05:42,good,85,92

Vital Signs (ben_vitals_data.csv)

date,systolic_bp,diastolic_bp,heart_rate,temperature_f,weight_kg,glucose_mg_dl
2024-09-14,142,88,72,98.6,78.2,156

🧪 Testing

# Test MCP server functionality
python test_server.py

# Test tool configuration
python manage_tools.py list

# Test web application
curl http://localhost:8000/health

# Run comprehensive tests
./run_tests.sh

🤝 Contributing

1. Fork the repository
2. Create feature branch (git checkout -b feature/amazing-feature)
3. Commit changes (git commit -m 'Add amazing feature')
4. Push to branch (git push origin feature/amazing-feature)
5. Open Pull Request

📄 License

This project is licensed under the MIT License - see the file for details.

🆘 Support

• Issues: GitHub Issues
• Documentation: See individual module docstrings
• Examples: Check the examples/ directory

⚠️ Medical Disclaimer

This tool provides general medical information for educational and professional reference purposes only. It is not intended to be a substitute for professional medical advice, diagnosis, or treatment. Always seek the advice of qualified healthcare providers with any questions regarding medical conditions or treatment decisions.

Built with ❤️ for healthcare professionals and medical AI research