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