Healthcare MCP Server

Created By

Cicatriiz8 months ago

A 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.

# python

# docker

Overview Content Tools Comments

Content

Healthcare MCP Server

A Model Context Protocol (MCP) server providing AI assistants with access to healthcare data and medical information tools.

Overview

Healthcare MCP Server is a specialized server that implements the Model Context Protocol (MCP) to provide AI assistants with access to healthcare data and medical information tools. It enables AI models to retrieve accurate, up-to-date medical information from authoritative sources.

Features

FDA Drug Information: Search and retrieve comprehensive drug information from the FDA database
PubMed Research: Search medical literature from PubMed's database of scientific articles
Health Topics: Access evidence-based health information from Health.gov
Clinical Trials: Search for ongoing and completed clinical trials
Medical Terminology: Look up ICD-10 codes and medical terminology definitions
Caching: Efficient caching system with connection pooling to reduce API calls and improve performance
Usage Tracking: Anonymous usage tracking to monitor API usage
Error Handling: Robust error handling and logging
Multiple Interfaces: Support for both stdio (for CLI) and HTTP/SSE interfaces
API Documentation: Interactive API documentation with Swagger UI
Comprehensive Testing: Extensive test suite with pytest and coverage reporting

Installation

Manual Installation

Clone the repository:

git clone https://github.com/Cicatriiz/healthcare-mcp-public.git
cd healthcare-mcp-public

Create a virtual environment:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

Install dependencies:
```
pip install -r requirements.txt
```

Set up environment variables (optional):

# Create .env file from example
cp .env.example .env
# Edit .env with your API keys (optional)

Run the server:
```
python run.py
```

Usage

Running in Different Transport Modes

stdio mode (default, for Cline):
```
python run.py
```
HTTP/SSE mode (for web clients):
```
python run.py --http --port 8000
```

Testing the Tools

You can test the MCP tools using the new pytest-based test suite:

# Run all tests with pytest and coverage
python -m tests.run_tests --pytest

# Run a specific test file
python -m tests.run_tests --test test_fda_tool.py

# Test the HTTP server
python -m tests.run_tests --server --port 8000

For backward compatibility, you can still run the old tests:

# Run all tests (old style)
python -m tests.run_tests

# Test individual tools (old style)
python -m tests.run_tests --fda        # Test FDA drug lookup
python -m tests.run_tests --pubmed     # Test PubMed search
python -m tests.run_tests --health     # Test Health Topics
python -m tests.run_tests --trials     # Test Clinical Trials search
python -m tests.run_tests --icd        # Test ICD-10 code lookup

API Reference

The Healthcare MCP Server provides both a programmatic API for direct integration and a RESTful HTTP API for web clients.

RESTful API Endpoints

When running in HTTP mode, the following endpoints are available:

Health Check

GET /health

Returns the status of the server and its services.

FDA Drug Lookup

GET /api/fda?drug_name={drug_name}&search_type={search_type}

Parameters:

drug_name: Name of the drug to search for
search_type: Type of information to retrieve
- general: Basic drug information (default)
- label: Drug labeling information
- adverse_events: Reported adverse events

Example Response:

{
  "status": "success",
  "drug_name": "aspirin",
  "search_type": "general",
  "total_results": 25,
  "results": [
    {
      "brand_name": "ASPIRIN",
      "generic_name": "ASPIRIN",
      "manufacturer": "Bayer Healthcare",
      "product_type": "HUMAN OTC DRUG",
      "route": "ORAL",
      "active_ingredients": [
        {
          "name": "ASPIRIN",
          "strength": "325 mg/1"
        }
      ]
    }
  ]
}

PubMed Search

GET /api/pubmed?query={query}&max_results={max_results}&date_range={date_range}

Parameters:

query: Search query for medical literature
max_results: Maximum number of results to return (default: 5, max: 50)
date_range: Limit to articles published within years (e.g. '5' for last 5 years)

Example Response:

{
  "status": "success",
  "query": "diabetes treatment",
  "total_results": 123456,
  "date_range": "5",
  "articles": [
    {
      "pmid": "12345678",
      "title": "New advances in diabetes treatment",
      "authors": ["Smith J", "Johnson A"],
      "journal": "Journal of Diabetes Research",
      "publication_date": "2023-01-15",
      "abstract": "This study explores new treatment options...",
      "url": "https://pubmed.ncbi.nlm.nih.gov/12345678/"
    }
  ]
}

Health Topics

GET /api/health_finder?topic={topic}&language={language}

Parameters:

topic: Health topic to search for information
language: Language for content (en or es, default: en)

Example Response:

{
  "status": "success",
  "search_term": "diabetes",
  "language": "en",
  "total_results": 15,
  "topics": [
    {
      "title": "Diabetes Type 2",
      "url": "https://health.gov/myhealthfinder/topics/health-conditions/diabetes/diabetes-type-2",
      "last_updated": "2023-05-20",
      "section": "Health Conditions",
      "description": "Information about managing type 2 diabetes",
      "content": ["Diabetes is a disease...", "Treatment options include..."]
    }
  ]
}

Clinical Trials Search

GET /api/clinical_trials?condition={condition}&status={status}&max_results={max_results}

Parameters:

condition: Medical condition or disease to search for
status: Trial status (recruiting, completed, active, not_recruiting, or all)
max_results: Maximum number of results to return (default: 10, max: 100)

Example Response:

{
  "status": "success",
  "condition": "breast cancer",
  "search_status": "recruiting",
  "total_results": 256,
  "trials": [
    {
      "nct_id": "NCT12345678",
      "title": "Study of New Treatment for Breast Cancer",
      "status": "Recruiting",
      "phase": "Phase 2",
      "study_type": "Interventional",
      "conditions": ["Breast Cancer", "HER2-positive Breast Cancer"],
      "locations": [
        {
          "facility": "Memorial Hospital",
          "city": "New York",
          "state": "NY",
          "country": "United States"
        }
      ],
      "sponsor": "National Cancer Institute",
      "url": "https://clinicaltrials.gov/study/NCT12345678",
      "eligibility": {
        "gender": "Female",
        "min_age": "18 Years",
        "max_age": "75 Years",
        "healthy_volunteers": "No"
      }
    }
  ]
}

ICD-10 Code Lookup

GET /api/medical_terminology?code={code}&description={description}&max_results={max_results}

Parameters:

code: ICD-10 code to look up (optional if description is provided)
description: Medical condition description to search for (optional if code is provided)
max_results: Maximum number of results to return (default: 10, max: 50)

Example Response:

{
  "status": "success",
  "search_type": "description",
  "search_term": "diabetes",
  "total_results": 25,
  "codes": [
    {
      "code": "E11",
      "description": "Type 2 diabetes mellitus",
      "category": "Endocrine, nutritional and metabolic diseases"
    },
    {
      "code": "E10",
      "description": "Type 1 diabetes mellitus",
      "category": "Endocrine, nutritional and metabolic diseases"
    }
  ]
}

Generic Tool Execution

POST /mcp/call-tool

Request Body:

{
  "name": "fda_drug_lookup",
  "arguments": {
    "drug_name": "aspirin",
    "search_type": "general"
  },
  "session_id": "optional-session-id"
}

Programmatic API

When using the MCP server programmatically, the following functions are available:

FDA Drug Lookup

fda_drug_lookup(drug_name: str, search_type: str = "general")

Parameters:

drug_name: Name of the drug to search for
search_type: Type of information to retrieve
- general: Basic drug information (default)
- label: Drug labeling information
- adverse_events: Reported adverse events

PubMed Search

pubmed_search(query: str, max_results: int = 5, date_range: str = "")

Parameters:

query: Search query for medical literature
max_results: Maximum number of results to return (default: 5)
date_range: Limit to articles published within years (e.g. '5' for last 5 years)

Health Topics

health_topics(topic: str, language: str = "en")

Parameters:

topic: Health topic to search for information
language: Language for content (en or es, default: en)

Clinical Trials Search

clinical_trials_search(condition: str, status: str = "recruiting", max_results: int = 10)

Parameters:

condition: Medical condition or disease to search for
status: Trial status (recruiting, completed, active, not_recruiting, or all)
max_results: Maximum number of results to return

ICD-10 Code Lookup

lookup_icd_code(code: str = None, description: str = None, max_results: int = 10)

Parameters:

code: ICD-10 code to look up (optional if description is provided)
description: Medical condition description to search for (optional if code is provided)
max_results: Maximum number of results to return