Medical Calculator MCP Service

中文版 | English

Medical Calculator MCP Service Implementation.

🚀 Project Overview

This is a Medical Calculator MCP service implementation that has completed 56 medical calculators covering multiple medical fields including anthropometry, cardiovascular, renal function, hepatic function, laboratory tests, critical care scoring, respiratory system, infection & inflammation, fluid & medication, obstetrics, and oncology.

🏥 Calculator Categories

Anthropometry and Basic Calculations (5)

• BMI Calculator - Body Mass Index calculation
• Body Surface Area Calculator - BSA calculation
• Ideal Body Weight Calculator - IBW calculation
• Adjusted Body Weight Calculator - ABW calculation
• Target Weight Calculator

Cardiovascular System (11)

• Mean Arterial Pressure Calculator
• QTc Interval Calculators (5 formulas)
• CHA2DS2-VASc Stroke Risk Score
• HAS-BLED Bleeding Risk Score
• HEART Score Calculator
• Cardiac Risk Index Calculator
• Framingham Risk Score
• Wells DVT Score
• Caprini Thrombosis Risk Assessment

Renal Function (4)

• Creatinine Clearance Calculator (Cockcroft-Gault)
• CKD-EPI GFR Calculator
• MDRD GFR Calculator
• Fractional Excretion of Sodium Calculator

Hepatic Function (3)

• Child-Pugh Liver Function Classification
• MELD-Na Score Calculator
• FIB-4 Liver Fibrosis Index

Laboratory Tests (12)

• Anion Gap Calculator and related calculators
• Calcium Correction Calculator
• Sodium Correction for Hyperglycemia
• Serum Osmolality Calculator
• LDL Cholesterol Calculator
• HOMA-IR Insulin Resistance Index
• Free Water Deficit Calculator

Critical Care and Scoring Systems (8)

• APACHE II Acute Physiology Score
• SOFA Sequential Organ Failure Assessment
• SIRS Systemic Inflammatory Response Syndrome
• Glasgow Coma Score
• Glasgow Bleeding Score
• Charlson Comorbidity Index

Respiratory System (4)

• CURB-65 Pneumonia Severity Score
• Pneumonia Severity Index (PSI)
• Wells PE Score
• PERC Pulmonary Embolism Rule-out Criteria

Infection and Inflammation (2)

• Centor Streptococcal Pharyngitis Score
• FeverPAIN Pharyngitis Score

Fluid and Medication (3)

• Maintenance Fluid Calculator
• Steroid Conversion Calculator
• Morphine Milligram Equivalent Calculator

Obstetrics (3)

• Estimated Conception Date Calculator
• Estimated Gestational Age Calculator
• Estimated Due Date Calculator

Oncology (1)

• Lung Cancer TNM Staging Calculator

📚 Quick Start

1. Install Dependencies:

   pip install -r requirements.txt
   

2. Run Tests:

   # Run all API tests
   python test/api_test_bmi_calculator.py
   python test/api_test_pregnancy_calculators.py
   python test/api_test_lung_cancer_staging.py
   python test/api_test_tools.py
   
   # Run basic tests
   python test_bmi.py
   

3. Start Server:

   python server.py
   

📁 Project Structure

medcalcmcp/
├── medcalc/                           # Core framework module
│   ├── __init__.py                   # Module exports
│   ├── models.py                     # Data models
│   ├── base.py                       # Base calculator class
│   ├── registry.py                   # Calculator registration system
│   ├── service.py                    # Calculator service
│   ├── utils.py                      # Utilities (unit conversion, etc.)
│   └── exceptions.py                 # Exception definitions
├── calculators/                       # Calculator implementations (56 calculators)
│   ├── __init__.py                   # Calculator package (manages all calculators)
│   ├── bmi_calculator.py             # BMI Calculator
│   ├── bsa_calculator.py             # Body Surface Area Calculator
│   ├── creatinine_clearance_calculator.py  # Creatinine Clearance Calculator
│   ├── cha2ds2_vasc_calculator.py    # CHA2DS2-VASc Score
│   ├── lung_cancer_staging_calculator.py  # Lung Cancer TNM Staging Calculator
│   └── ...                          # Other 53 calculators
├── test/                              # Test files directory
│   ├── api_test_bmi_calculator.py    # BMI Calculator API tests
│   ├── api_test_pregnancy_calculators.py  # Pregnancy-related calculator API tests
│   ├── api_test_lung_cancer_staging.py    # Lung cancer staging calculator API tests
│   └── api_test_tools.py             # MCP tools dynamic tests
├── server.py                          # FastMCP server main file
├── api_server.py                      # MCP API server
├── requirements.txt                   # Project dependencies
└── README.md                          # Project documentation

🛠️ Technical Architecture

The project uses a modular design with the following main components:

• MCP Server (server.py): Provides MCP protocol interface
• Core Framework (medcalc/): Data models, base classes, utilities
• Calculator Engine (calculators/): 56 specific medical calculators
• Test Suite (test/): API tests and functionality verification

✨ Key Features

• ✅ Complete Medical Calculator Collection: 56 professional medical calculators
• ✅ Multi-domain Coverage: Covers various clinical medical specialties
• ✅ Smart Unit Conversion: Supports automatic conversion of various medical units
• ✅ Detailed Calculation Explanations: Each result includes detailed medical explanations
• ✅ Complete Parameter Validation: Ensures accuracy and safety of input data
• ✅ MCP Protocol Support: Standardized interface protocol
• ✅ Asynchronous Processing: High-performance asynchronous calculation processing
• ✅ Complete Test Coverage: Comprehensive API and functionality testing

🚀 Start Server

# Start FastMCP server (recommended)
python server.py

# Or start MCP API server
python api_server.py
# Server will run at http://127.0.0.1:8010/mcp/

🔧 Development Guide

Creating New Calculators

1. Create a new calculator file in the calculators/ directory
2. Inherit from the BaseCalculator class
3. Implement required methods: get_info(), validate_parameters(), calculate()
4. Register using the @register_calculator decorator
5. Add import to calculators/__init__.py

Running Tests

# Test specific calculator
python test/api_test_bmi_calculator.py

# Test all calculators (dynamic testing)
python test/api_test_tools.py

# Test pregnancy-related calculators
python test/api_test_pregnancy_calculators.py

# Test lung cancer staging calculator
python test/api_test_lung_cancer_staging.py

📋 Project Status

• Current Version: 0.1.0
• Number of Calculators: 56
• Test Coverage: 100%
• Supported Medical Fields: 11 specialty areas

🤝 Contributing

Pull requests and issues are welcome to help improve the project.

🙏 Acknowledgments

This project is based on the MedCalc-Bench project. Thanks to the NCBI-NLP team for providing excellent foundational medical calculator implementations. We have converted it into an MCP (Model Context Protocol) service to better integrate with modern AI applications.

Original Project References:

• GitHub: https://github.com/ncbi-nlp/MedCalc-Bench
• Paper: MedCalc-Bench: A Large-scale Medical Calculator Benchmark