Unofficial Medicare MCP Server

A Model Context Protocol (MCP) server providing comprehensive access to CMS Medicare data via the Socrata API, including physician/practitioner services, prescriber data, hospital utilization, and drug spending. This server enables AI assistants and applications to search and analyze Medicare payment, utilization, and coverage information.

Features

• Provider Data: CMS Medicare Physician & Other Practitioners data from 2013-2023 with automatic latest-year selection
• Prescriber Data: Medicare Part D prescriber information by drug, provider, and geography
• Hospital Data: Medicare inpatient hospital utilization and payment data
• Hospital Quality Metrics: Star ratings, readmission rates, mortality rates, and hospital-acquired infections (HAI)
• Drug Spending: Medicare Part D and Part B drug spending trends
• Formulary Data: Medicare Part D plan formulary coverage with automated monthly updates
• ASP Pricing: Medicare Part B Average Sales Price data for physician-administered drugs
• Flexible Querying: Advanced filtering, pagination, and field selection
• TypeScript: Fully typed codebase with strict mode enabled
• Production Ready: Health checks and comprehensive logging
• Unified Tool Interface: Single medicare_info tool with method-based routing for different data types
• Automated Updates: GitHub Actions workflows for data freshness
  • Formulary: Monthly checks on the 15th (after CMS releases)
  • ASP Pricing: Quarterly checks on 15th of Jan/Apr/Jul/Oct

Usage

{
  "mcpServers": {
    "medicare-mcp-server": {
      "command": "node",
      "args": ["/path/to/medicare-mcp-server/build/index.js"]
    }
  }
}

Tool Description

Medicare Info Tool

The medicare_info tool provides unified access to Medicare data using the method parameter to select the operation type:

1. search_providers: Medicare Physician & Other Practitioners data (2013-2023)
2. search_prescribers: Medicare Part D prescriber data by drug, provider NPI, specialty, and state
3. search_hospitals: Medicare inpatient hospital utilization and payment data
4. search_spending: Medicare Part D and Part B drug spending trends
5. search_formulary: Medicare Part D plan formulary coverage (tier, prior auth, quantity limits, step therapy)
6. get_hospital_star_rating: Hospital overall quality star ratings (1-5 stars)
7. get_readmission_rates: Hospital 30-day readmission rates by condition
8. get_hospital_infections: Hospital-acquired infections (HAI) data
9. get_mortality_rates: Hospital 30-day mortality rates by condition
10. search_hospitals_by_quality: Search hospitals by quality metrics and filters
11. compare_hospitals: Compare multiple hospitals across quality metrics
12. get_vbp_scores: Hospital Value-Based Purchasing (VBP) performance scores
13. get_hcahps_scores: Patient experience (HCAHPS) survey scores
14. get_asp_pricing: Get ASP pricing for Medicare Part B drugs
15. get_asp_trend: Track ASP pricing changes over multiple quarters
16. compare_asp_pricing: Compare ASP pricing across multiple drugs
17. get_formulary_trend: Track formulary policy changes over time (prior auth, tiers, coverage)

---

Method 1: search_providers

Search Medicare Physician & Other Practitioners data using the Centers for Medicare & Medicaid Services (CMS) database. This data includes information about services and procedures provided to Original Medicare Part B beneficiaries. The tool supports data from 2013 to the latest available year, defaulting to the latest year if not specified.

Parameters

• dataset_type (required): Type of dataset to search
  • geography_and_service: Use when you need to:
    • Compare regions
    • Analyze geographic patterns
    • Study regional variations in healthcare delivery
    • Understand geographic distribution of healthcare services
    • Calculate per-capita/per-beneficiary rates by region
  • provider_and_service: Use when you need to:
    • Analyze individual provider performance
    • Track specific procedures by provider
    • Calculate total procedures across providers
    • Study provider-level service patterns and outcomes
  • provider: Use when you need to:
    • Analyze provider demographics
    • Study provider participation in Medicare
    • Understand provider practice patterns
    • Examine provider-level beneficiary characteristics and risk scores
• year (optional): Year of the dataset to query (2013 to 2023, defaults to latest year). Note that data availability may vary by year and dataset type.
• hcpcs_code (optional): HCPCS code to search for (e.g., '99213' for established patient office visit). Can be used to analyze specific procedures or services.
• provider_type (optional): Type of provider to search for (e.g., 'Cardiology', 'Podiatry', 'Family Practice'). Supports partial matches and is case-insensitive.
• geo_level (optional): Geographic level for filtering (e.g., "National", "State", "County", "ZIP"). Use with geo_code to filter results by specific geographic areas.
• geo_code (optional): Geographic code to filter by (e.g., 'CA' for California, '06037' for Los Angeles County). Must match the geo_level specified.
• place_of_service (optional): Place of service code to filter by (e.g., 'F' for facility, 'O' for office, 'H' for hospital). See CMS documentation for complete list of codes.
• size (optional): Number of results to return (default: 10, max: 5000). Use with offset for pagination of large result sets.
• offset (optional): Starting result number for pagination (default: 0). Use with size to navigate through large result sets.
• sort_by (optional): Field to sort results by. Common fields include 'Tot_Srvcs' (total services), 'Tot_Benes' (total beneficiaries), 'Tot_Mdcr_Pymt_Amt' (total Medicare payment).
• sort_order (optional): Sort order ("asc" or "desc", default: "desc").

Response Fields

The response fields vary by dataset type:

For geography_and_service dataset:

• Rndrng_Prvdr_Geo_Lvl: Geographic level (National, State, County, ZIP)
• Rndrng_Prvdr_Geo_Cd: Geographic code (e.g., 'CA' for California)
• Rndrng_Prvdr_Geo_Desc: Geographic description
• HCPCS_Cd: HCPCS code
• HCPCS_Desc: Description of the service/procedure
• HCPCS_Drug_Ind: Indicates if the service is drug-related
• Place_Of_Srvc: Place of service code
• Tot_Rndrng_Prvdrs: Total number of rendering providers
• Tot_Benes: Total number of beneficiaries
• Tot_Srvcs: Total number of services
• Tot_Bene_Day_Srvcs: Total beneficiary days of service
• Avg_Sbmtd_Chrg: Average submitted charge
• Avg_Mdcr_Alowd_Amt: Average Medicare allowed amount
• Avg_Mdcr_Pymt_Amt: Average Medicare payment amount
• Avg_Mdcr_Stdzd_Amt: Average standardized Medicare payment amount

For provider_and_service dataset:

• Rndrng_NPI: Provider's National Provider Identifier
• Rndrng_Prvdr_Last_Org_Name: Provider's last name or organization name
• Rndrng_Prvdr_First_Name: Provider's first name
• Rndrng_Prvdr_MI: Provider's middle initial
• Rndrng_Prvdr_Crdntls: Provider's credentials
• Rndrng_Prvdr_Ent_Cd: Provider's entity type
• Rndrng_Prvdr_St1: Provider's street address
• Rndrng_Prvdr_City: Provider's city
• Rndrng_Prvdr_State_Abrvtn: Provider's state
• Rndrng_Prvdr_Zip5: Provider's ZIP code
• Rndrng_Prvdr_Type: Provider's specialty/type
• Rndrng_Prvdr_Mdcr_Prtcptg_Ind: Medicare participating indicator
• HCPCS_Cd: HCPCS code
• HCPCS_Desc: Description of the service/procedure
• Place_Of_Srvc: Place of service code
• Tot_Benes: Total number of beneficiaries
• Tot_Srvcs: Total number of services
• Tot_Bene_Day_Srvcs: Total beneficiary days of service
• Avg_Sbmtd_Chrg: Average submitted charge
• Avg_Mdcr_Alowd_Amt: Average Medicare allowed amount
• Avg_Mdcr_Pymt_Amt: Average Medicare payment amount
• Avg_Mdcr_Stdzd_Amt: Average standardized Medicare payment amount

For provider dataset:

• Rndrng_NPI: Provider's National Provider Identifier
• Rndrng_Prvdr_Last_Org_Name: Provider's last name or organization name
• Rndrng_Prvdr_First_Name: Provider's first name
• Rndrng_Prvdr_MI: Provider's middle initial
• Rndrng_Prvdr_Crdntls: Provider's credentials
• Rndrng_Prvdr_Ent_Cd: Provider's entity type
• Rndrng_Prvdr_St1: Provider's street address
• Rndrng_Prvdr_City: Provider's city
• Rndrng_Prvdr_State_Abrvtn: Provider's state
• Rndrng_Prvdr_Zip5: Provider's ZIP code
• Rndrng_Prvdr_Type: Provider's specialty/type
• Rndrng_Prvdr_Mdcr_Prtcptg_Ind: Medicare participating indicator
• Tot_HCPCS_Cds: Total number of unique HCPCS codes
• Tot_Benes: Total number of beneficiaries
• Tot_Srvcs: Total number of services
• Tot_Sbmtd_Chrg: Total submitted charges
• Tot_Mdcr_Alowd_Amt: Total Medicare allowed amount
• Tot_Mdcr_Pymt_Amt: Total Medicare payment amount
• Tot_Mdcr_Stdzd_Amt: Total standardized Medicare payment amount
• Bene_Avg_Age: Average beneficiary age
• Bene_Age_LT_65_Cnt: Number of beneficiaries under 65
• Bene_Age_65_74_Cnt: Number of beneficiaries aged 65-74
• Bene_Age_75_84_Cnt: Number of beneficiaries aged 75-84
• Bene_Age_GT_84_Cnt: Number of beneficiaries over 84
• Bene_Feml_Cnt: Number of female beneficiaries
• Bene_Male_Cnt: Number of male beneficiaries
• Bene_Race_Wht_Cnt: Number of white beneficiaries
• Bene_Race_Black_Cnt: Number of black beneficiaries
• Bene_Race_API_Cnt: Number of Asian/Pacific Islander beneficiaries
• Bene_Race_Hspnc_Cnt: Number of Hispanic beneficiaries
• Bene_Race_NatInd_Cnt: Number of Native American beneficiaries
• Bene_Race_Othr_Cnt: Number of beneficiaries of other races
• Bene_Dual_Cnt: Number of dual-eligible beneficiaries
• Bene_Ndual_Cnt: Number of non-dual-eligible beneficiaries
• Bene_Avg_Risk_Scre: Average beneficiary risk score

Example Queries

Geography and Service Dataset Examples

1. Find all office visits (HCPCS 99213) in California for 2023:

{
  "dataset_type": "geography_and_service",
  "geo_level": "State",
  "geo_code": "CA",
  "hcpcs_code": "99213",
  "year": 2023
}

2. Compare knee replacement procedures (HCPCS 27447) across different states:

{
  "dataset_type": "geography_and_service",
  "geo_level": "State",
  "hcpcs_code": "27447",
  "year": 2023,
  "sort_by": "Tot_Srvcs",
  "sort_order": "desc",
  "size": 10
}

3. Analyze Medicare spending on specific procedures in Los Angeles County:

{
  "dataset_type": "geography_and_service",
  "geo_level": "County",
  "geo_code": "06037",
  "hcpcs_code": "27130",
  "year": 2023
}

Provider and Service Dataset Examples

1. Find providers performing knee replacements in California:

{
  "dataset_type": "provider_and_service",
  "geo_level": "State",
  "geo_code": "CA",
  "hcpcs_code": "27447",
  "year": 2023,
  "sort_by": "Tot_Srvcs",
  "sort_order": "desc",
  "size": 10
}

2. Search for cardiologists performing specific procedures:

{
  "dataset_type": "provider_and_service",
  "provider_type": "Cardiology",
  "hcpcs_code": "93010",
  "year": 2023,
  "sort_by": "Tot_Srvcs",
  "sort_order": "desc"
}

Provider Dataset Examples

1. Find top providers by total services in California:

{
  "dataset_type": "provider",
  "geo_level": "State",
  "geo_code": "CA",
  "year": 2023,
  "sort_by": "Tot_Srvcs",
  "sort_order": "desc",
  "size": 10
}

2. Search for providers by specialty with beneficiary demographics:

{
  "dataset_type": "provider",
  "provider_type": "Orthopedic Surgery",
  "year": 2023,
  "sort_by": "Tot_Benes",
  "sort_order": "desc"
}

Common Use Cases

1. Geographic Analysis

   • Compare healthcare utilization across different regions
   • Identify areas with high or low service volumes
   • Analyze regional variations in Medicare payments
   • Track service patterns by geographic level

2. Provider Analysis

   • Identify high-volume providers
   • Compare provider practice patterns
   • Analyze provider-level beneficiary characteristics
   • Track provider participation in Medicare

3. Service Analysis

   • Compare utilization of specific procedures
   • Analyze Medicare payment patterns
   • Track service volumes over time
   • Identify trends in healthcare delivery

4. Beneficiary Analysis

   • Analyze beneficiary demographics
   • Track risk scores and health status
   • Compare dual-eligible vs. non-dual-eligible populations
   • Monitor age and gender distributions

5. Payment Analysis

   • Compare submitted charges vs. Medicare payments
   • Analyze payment variations by region
   • Track standardized payment amounts
   • Monitor Medicare payment trends

---

Method 2: search_prescribers

Search Medicare Part D prescriber data to analyze drug prescribing patterns by provider, specialty, geography, and drug name. This method provides access to CMS Part D Prescribers - by Provider and Drug dataset.

Parameters

• method (required): Must be set to "search_prescribers"
• drug_name (optional): Drug brand name to search for (e.g., 'Ozempic', 'Humira', 'Eliquis'). Searches brand names only.
• prescriber_npi (optional): National Provider Identifier (NPI) of the prescriber
• prescriber_type (optional): Prescriber specialty (e.g., 'Endocrinology', 'Family Practice', 'Internal Medicine')
• state (optional): State abbreviation (e.g., 'CA', 'TX', 'NY')
• size (optional): Number of results to return (default: 10)
• offset (optional): Starting result number for pagination (default: 0)

Response Format

{
  "total": 3,
  "prescribers": [
    {
      "npi": "1003002049",
      "prescriber_name": "Srinivasan, Lakshmi",
      "prescriber_type": "Endocrinology",
      "city": "Fremont",
      "state": "CA",
      "brand_name": "Ozempic",
      "generic_name": "Semaglutide",
      "total_claims": "113",
      "total_30day_fills": "230.7",
      "total_drug_cost": "236624.18",
      "total_beneficiaries": "25"
    }
  ]
}

Example Queries

1. Find California prescribers of Ozempic

{
  "method": "search_prescribers",
  "drug_name": "Ozempic",
  "state": "CA",
  "size": 10
}

2. Find endocrinologists prescribing GLP-1 drugs in Texas

{
  "method": "search_prescribers",
  "prescriber_type": "Endocrinology",
  "state": "TX",
  "size": 20
}

3. Lookup specific prescriber by NPI

{
  "method": "search_prescribers",
  "prescriber_npi": "1003002049"
}

---

Method 3: search_hospitals

Search Medicare inpatient hospital utilization and payment data. This method provides access to CMS Medicare Inpatient Hospitals - by Provider dataset, showing discharge volumes, charges, and payment amounts.

Parameters

• method (required): Must be set to "search_hospitals"
• hospital_name (optional): Hospital name (partial match supported, e.g., 'MAYO', 'Memorial')
• hospital_id (optional): CMS Certification Number (CCN) or provider ID
• state (optional): State abbreviation (e.g., 'TX', 'CA', 'NY')
• city (optional): City name
• drg_code (optional): Diagnosis Related Group (DRG) code
• size (optional): Number of results to return (default: 10)
• offset (optional): Starting result number for pagination (default: 0)

Response Format

{
  "total": 3,
  "hospitals": [
    {
      "ccn": "450002",
      "hospital_name": "The Hospitals Of Providence Memorial Campus",
      "street_address": "2001 N Oregon St",
      "city": "El Paso",
      "state": "TX",
      "zip": "79902",
      "total_discharges": "950"
    }
  ]
}

Example Queries

1. Find Texas hospitals

{
  "method": "search_hospitals",
  "state": "TX",
  "size": 10
}

2. Search for Mayo Clinic facilities

{
  "method": "search_hospitals",
  "hospital_name": "MAYO",
  "size": 10
}

3. Find hospitals in specific city

{
  "method": "search_hospitals",
  "city": "Houston",
  "state": "TX",
  "size": 20
}

---

Method 4: search_spending

Search Medicare Part D and Part B drug spending trends. This method provides access to CMS drug spending datasets showing total spending, claims, beneficiaries, and average costs per claim and per beneficiary.

Parameters

• method (required): Must be set to "search_spending"
• spending_drug_name (optional): Drug brand name to search for (e.g., 'Ozempic', 'Humira', 'Eliquis')
• spending_type (optional): Type of spending data - 'part_d' (prescription drugs) or 'part_b' (administered drugs). Default: 'part_d'
• year (optional): Data year to filter by
• size (optional): Number of results to return (default: 10)
• offset (optional): Starting result number for pagination (default: 0)

Response Format

{
  "total": 2,
  "spending_type": "part_d",
  "drugs": [
    {
      "brand_name": "Ozempic",
      "generic_name": "Semaglutide",
      "year": "2022",
      "total_spending": "5234567890.45",
      "total_claims": "1234567",
      "total_beneficiaries": "234567",
      "average_spending_per_claim": "4238.12",
      "average_spending_per_beneficiary": "22314.56"
    }
  ]
}

Example Queries

1. Find Part D spending for Ozempic

{
  "method": "search_spending",
  "spending_drug_name": "Ozempic",
  "spending_type": "part_d",
  "size": 5
}

2. Get Part B drug spending trends

{
  "method": "search_spending",
  "spending_type": "part_b",
  "size": 20
}

3. Find spending for specific year

{
  "method": "search_spending",
  "spending_drug_name": "Humira",
  "year": "2022"
}

---

Method 5: search_formulary

Search Medicare Part D plan formulary coverage using local CMS formulary data files. Returns drug coverage information including tier level, prior authorization requirements, quantity limits, and step therapy requirements across Medicare Part D plans.

Parameters

• formulary_drug_name (optional): Drug name to search for (partial match supported, e.g., 'metformin', 'insulin'). Uses RxNorm API to convert drug names to RXCUI codes. At least one of formulary_drug_name or ndc_code is required.
• ndc_code (optional): NDC (National Drug Code) for exact drug identification (e.g., '00002143380'). At least one of formulary_drug_name or ndc_code is required.
• tier (optional): Tier number to filter by:
  • 1 = Preferred Generic
  • 2 = Generic
  • 3 = Preferred Brand
  • 4 = Non-Preferred Brand
  • 5 = Specialty
  • 6 = Select Care
• requires_prior_auth (optional): Filter by prior authorization requirement (true=requires PA, false=no PA required)
• has_quantity_limit (optional): Filter by quantity limit (true=has limit, false=no limit)
• has_step_therapy (optional): Filter by step therapy requirement (true=requires ST, false=no ST required)
• plan_state (optional): State abbreviation to filter plans (e.g., 'CA', 'TX', 'NY')
• plan_id (optional): Medicare Part D plan ID to filter by specific plan
• size (optional): Number of results to return (default: 25, max: 5000)
• offset (optional): Starting result number for pagination (default: 0)

Response Fields

• total: Total number of matching formulary entries
• offset: Starting position for pagination
• limit: Maximum results returned
• drug_name_searched: Drug name that was searched (if provided)
• rxcuis_found: Array of RXCUI codes found for the drug name
• formulary_entries: Array of formulary entries with:
  • formulary_id: Plan formulary ID
  • plan_name: Medicare Part D plan name
  • state: State where plan is available
  • rxcui: RxNorm Concept Unique Identifier
  • ndc: National Drug Code
  • tier_level: Tier number (1-6)
  • quantity_limit: Whether quantity limit applies (boolean)
  • quantity_limit_amount: Maximum quantity allowed
  • quantity_limit_days: Days supply for quantity limit
  • prior_authorization: Whether prior authorization required (boolean)
  • step_therapy: Whether step therapy required (boolean)

Example Queries

1. Search by drug name

{
  "method": "search_formulary",
  "formulary_drug_name": "metformin",
  "size": 10
}

2. Find drugs without prior authorization in California

{
  "method": "search_formulary",
  "formulary_drug_name": "insulin",
  "plan_state": "CA",
  "requires_prior_auth": false,
  "size": 20
}

3. Search by NDC code

{
  "method": "search_formulary",
  "ndc_code": "00002143380",
  "size": 5
}

4. Find specialty tier drugs (tier 5)

{
  "method": "search_formulary",
  "formulary_drug_name": "Humira",
  "tier": 5
}

---

Method 6: get_hospital_star_rating

Get hospital overall quality star ratings (1-5 stars) from CMS Hospital Care Compare. Star ratings provide a comprehensive measure of hospital quality based on multiple clinical domains including mortality, safety, readmission, patient experience, and timely & effective care.

Parameters

• method (required): Must be set to "get_hospital_star_rating"
• quality_hospital_id (optional): CMS Certification Number (CCN) to lookup specific hospital (e.g., '050146')
• quality_state (optional): State abbreviation to filter hospitals (e.g., 'CA', 'TX', 'NY')
• size (optional): Number of results to return (default: 10)
• offset (optional): Starting result number for pagination (default: 0)

Response Format

{
  "total": 2,
  "hospitals": [
    {
      "facility_id": "050002",
      "facility_name": "ST ROSE HOSPITAL",
      "address": "27200 CALAROGA AVE",
      "city": "HAYWARD",
      "state": "CA",
      "zip_code": "94545",
      "hospital_overall_rating": "1",
      "hospital_type": "Acute Care Hospitals",
      "hospital_ownership": "Voluntary non-profit - Church",
      "emergency_services": false,
      "mortality_measures_count": "7",
      "safety_measures_count": "8",
      "readmission_measures_count": "11",
      "patient_experience_measures_count": "8"
    }
  ]
}

Example Queries

1. Get star ratings for California hospitals

{
  "method": "get_hospital_star_rating",
  "quality_state": "CA",
  "size": 10
}

2. Lookup specific hospital by CCN

{
  "method": "get_hospital_star_rating",
  "quality_hospital_id": "050146"
}

Use Cases

• Provider Network Selection: Identify high-quality hospitals (4-5 stars) for preferred networks
• Quality Benchmarking: Compare hospital performance against competitors
• Market Analysis: Analyze quality distribution across geographic markets
• Contracting Strategy: Target high-performing hospitals for value-based contracts

---

Method 7: get_readmission_rates

Get hospital 30-day readmission rates by medical condition from CMS Unplanned Hospital Visits dataset. Readmission rates indicate how often patients return to the hospital within 30 days of discharge.

Parameters

• method (required): Must be set to "get_readmission_rates"
• quality_hospital_id (optional): CMS Certification Number (CCN) to lookup specific hospital
• quality_state (optional): State abbreviation to filter hospitals
• condition (optional): Medical condition to filter by:
  • heart_attack - Heart attack (AMI) 30-day readmission
  • heart_failure - Heart failure 30-day readmission
  • pneumonia - Pneumonia 30-day readmission
  • copd - COPD 30-day readmission
  • cabg - CABG surgery 30-day readmission
  • hip_knee - Hip/knee replacement 30-day readmission
• size (optional): Number of results to return (default: 10)
• offset (optional): Starting result number for pagination (default: 0)

Response Format

{
  "total": 2,
  "readmissions": [
    {
      "facility_id": "050002",
      "facility_name": "ST ROSE HOSPITAL",
      "state": "CA",
      "measure_id": "EDAC_30_HF",
      "measure_name": "Hospital return days for heart failure patients",
      "compared_to_national": "More Days Than Average per 100 Discharges",
      "score": "29.4",
      "denominator": "135",
      "lower_estimate": "9.4",
      "higher_estimate": "51.4",
      "number_of_patients": "103",
      "number_of_patients_returned": "43",
      "start_date": "07/01/2021",
      "end_date": "06/30/2024"
    }
  ]
}

Example Queries

1. Get heart failure readmissions in California

{
  "method": "get_readmission_rates",
  "quality_state": "CA",
  "condition": "heart_failure",
  "size": 20
}

2. Get all readmission measures for a specific hospital

{
  "method": "get_readmission_rates",
  "quality_hospital_id": "050146",
  "size": 50
}

Use Cases

• Drug Market Sizing: Identify hospitals with high HF readmissions for heart failure drug targeting
• Value-Based Contracting: Partner with hospitals to reduce readmissions through better medication management
• Quality Improvement Programs: Target hospitals with high readmission rates for clinical support programs
• Competitive Intelligence: Analyze readmission patterns to identify unmet medical needs

---

Method 8: get_hospital_infections

Get hospital-acquired infection (HAI) data including CLABSI, CAUTI, SSI, C.diff, and MRSA from CMS Healthcare Associated Infections dataset. Returns Standardized Infection Ratios (SIR) comparing observed vs. predicted infections.

Parameters

• method (required): Must be set to "get_hospital_infections"
• quality_hospital_id (optional): CMS Certification Number (CCN) to lookup specific hospital
• quality_state (optional): State abbreviation to filter hospitals
• infection_type (optional): Type of infection to filter by:
  • CLABSI - Central Line Associated Bloodstream Infection
  • CAUTI - Catheter-Associated Urinary Tract Infection
  • SSI - Surgical Site Infection
  • CDIFF - Clostridium Difficile Infection
  • MRSA - Methicillin-Resistant Staphylococcus Aureus
• size (optional): Number of results to return (default: 10)
• offset (optional): Starting result number for pagination (default: 0)

Response Format

{
  "total": 2,
  "infections": [
    {
      "facility_id": "050002",
      "facility_name": "ST ROSE HOSPITAL",
      "state": "CA",
      "measure_id": "HAI_1_SIR",
      "measure_name": "Central Line Associated Bloodstream Infection (ICU + select Wards)",
      "compared_to_national": "No Different than National Benchmark",
      "score": "0.000",
      "start_date": "01/01/2024",
      "end_date": "12/31/2024"
    }
  ]
}

Example Queries

1. Get CLABSI data for California hospitals

{
  "method": "get_hospital_infections",
  "quality_state": "CA",
  "infection_type": "CLABSI",
  "size": 20
}

2. Get all HAI data for a specific hospital

{
  "method": "get_hospital_infections",
  "quality_hospital_id": "050146"
}

Use Cases

• Antibiotic Market Targeting: Identify hospitals with high infection rates for antimicrobial stewardship programs
• Infection Control Budget Analysis: Estimate hospital spending on infection prevention
• Quality Improvement Partnerships: Partner with high-infection hospitals for clinical programs
• Device Market Sizing: Analyze infection burden for medical device targeting (central lines, catheters)

---

Method 9: get_mortality_rates

Get hospital 30-day mortality rates by medical condition from CMS Complications and Deaths dataset. Mortality rates show risk-adjusted death rates within 30 days of hospital admission.

Parameters

• method (required): Must be set to "get_mortality_rates"
• quality_hospital_id (optional): CMS Certification Number (CCN) to lookup specific hospital
• quality_state (optional): State abbreviation to filter hospitals
• condition (optional): Medical condition to filter by:
  • heart_attack - Heart attack (AMI) 30-day mortality
  • heart_failure - Heart failure 30-day mortality
  • pneumonia - Pneumonia 30-day mortality
  • cabg - CABG surgery 30-day mortality
  • copd - COPD 30-day mortality
  • stroke - Stroke 30-day mortality
• size (optional): Number of results to return (default: 10)
• offset (optional): Starting result number for pagination (default: 0)

Response Format

{
  "total": 5,
  "mortality": [
    {
      "facility_id": "050146",
      "facility_name": "CEDARS-SINAI MEDICAL CENTER",
      "state": "CA",
      "measure_id": "MORT_30_AMI",
      "measure_name": "Acute Myocardial Infarction (AMI) 30-Day Mortality Rate",
      "compared_to_national": "No Different than National Rate",
      "score": "13.8",
      "denominator": "450",
      "lower_estimate": "11.2",
      "higher_estimate": "16.8",
      "start_date": "07/01/2020",
      "end_date": "06/30/2023"
    }
  ]
}

Example Queries

1. Get heart attack mortality rates in California

{
  "method": "get_mortality_rates",
  "quality_state": "CA",
  "condition": "heart_attack",
  "size": 20
}

2. Get all mortality measures for a hospital

{
  "method": "get_mortality_rates",
  "quality_hospital_id": "050146"
}

Use Cases

• Outcomes-Based Contracting: Identify hospitals with better mortality outcomes for partnerships
• Clinical Trial Site Selection: Select high-quality hospitals for better patient outcomes
• Drug Efficacy Targeting: Target hospitals with high mortality for drugs that improve survival
• Quality Benchmarking: Compare hospital performance on life-threatening conditions

---

Method 10: search_hospitals_by_quality

Search and filter hospitals by quality metrics including minimum star ratings and geographic filters.

Parameters

• method (required): Must be set to "search_hospitals_by_quality"
• quality_state (optional): State abbreviation to filter hospitals
• min_star_rating (optional): Minimum star rating (1-5) to filter hospitals
• size (optional): Number of results to return (default: 10)
• offset (optional): Starting result number for pagination (default: 0)

Response Format

{
  "total": 5,
  "hospitals": [
    {
      "facility_id": "050146",
      "facility_name": "CEDARS-SINAI MEDICAL CENTER",
      "address": "8700 BEVERLY BLVD",
      "city": "LOS ANGELES",
      "state": "CA",
      "zip_code": "90048",
      "hospital_overall_rating": "5",
      "hospital_type": "Acute Care Hospitals",
      "hospital_ownership": "Voluntary non-profit - Private",
      "emergency_services": true
    }
  ]
}

Example Queries

1. Find 4-5 star hospitals in California

{
  "method": "search_hospitals_by_quality",
  "quality_state": "CA",
  "min_star_rating": 4,
  "size": 50
}

2. Find all 5-star hospitals nationwide

{
  "method": "search_hospitals_by_quality",
  "min_star_rating": 5,
  "size": 100
}

Use Cases

• Network Development: Build preferred provider networks with high-quality hospitals
• Market Entry Strategy: Identify top-performing hospitals for initial launch partnerships
• Geographic Expansion: Find quality hospitals in new markets
• Competitive Analysis: Analyze quality distribution in target markets

---

Method 11: compare_hospitals

Compare multiple hospitals across quality metrics including star ratings, readmission rates, mortality rates, and infection rates.

Parameters

• method (required): Must be set to "compare_hospitals"
• hospital_ids (required): Array of hospital CCN IDs to compare
• metrics (optional): Array of metrics to compare. Options:
  • star_rating - Overall quality star rating
  • readmission_rate - 30-day readmission rates
  • mortality_rate - 30-day mortality rates
  • infection_rate - Hospital-acquired infection rates
  • If not specified, returns all metrics
• size (optional): Number of results per metric (default: 100)

Response Format

{
  "hospitals": [
    {
      "facility_id": "050146",
      "facility_name": "CEDARS-SINAI MEDICAL CENTER",
      "star_rating": "5",
      "readmissions": [
        {
          "measure_id": "READM_30_HF",
          "measure_name": "Heart failure 30-day readmission",
          "score": "21.2",
          "compared_to_national": "Better than National Rate"
        }
      ],
      "mortality": [
        {
          "measure_id": "MORT_30_AMI",
          "measure_name": "Heart attack 30-day mortality",
          "score": "13.8",
          "compared_to_national": "No Different than National Rate"
        }
      ],
      "infections": [
        {
          "measure_id": "HAI_1_SIR",
          "measure_name": "CLABSI",
          "score": "0.326",
          "compared_to_national": "No Different than National Benchmark"
        }
      ]
    }
  ]
}

Example Queries

1. Compare three hospitals across all metrics

{
  "method": "compare_hospitals",
  "hospital_ids": ["050146", "050660", "050116"]
}

2. Compare hospitals on star rating and readmissions only

{
  "method": "compare_hospitals",
  "hospital_ids": ["050146", "050660"],
  "metrics": ["star_rating", "readmission_rate"]
}

Use Cases

• Contracting Decisions: Compare quality metrics before finalizing hospital contracts
• Competitive Benchmarking: Analyze how target hospitals compare to competitors
• Market Analysis: Compare quality across hospitals in same geographic market
• Performance Tracking: Monitor quality changes over time for partner hospitals

---

Method 12: get_vbp_scores

Get Hospital Value-Based Purchasing (VBP) performance scores from CMS. VBP scores measure hospital performance across four domains: Clinical Outcomes, Person & Community Engagement (patient experience), Safety, and Efficiency/Cost Reduction.

Parameters

• method (required): Must be set to "get_vbp_scores"
• quality_hospital_id (optional): CMS Certification Number (CCN) to lookup specific hospital
• quality_state (optional): State abbreviation to filter hospitals
• vbp_domain (optional): Filter by VBP domain:
  • clinical_outcomes - Clinical outcomes domain score only
  • person_community_engagement - Patient experience domain score only
  • safety - Safety domain score only
  • efficiency_cost_reduction - Efficiency/cost reduction domain score only
  • all or omit - Return all domain scores (default)
• size (optional): Number of results to return (default: 10)
• offset (optional): Starting result number for pagination (default: 0)

Response Format

{
  "total": 2,
  "vbp_scores": [
    {
      "facility_id": "050211",
      "facility_name": "ALAMEDA HOSPITAL",
      "state": "CA",
      "fiscal_year": "2025",
      "total_performance_score": "25.041666666667",
      "clinical_outcomes_score": "1.666666666667",
      "person_community_engagement_score": "2.750000000000",
      "safety_score": "20.625000000000",
      "efficiency_cost_reduction_score": "0.000000000000"
    }
  ]
}

Example Queries

1. Get all VBP scores for California hospitals

{
  "method": "get_vbp_scores",
  "quality_state": "CA",
  "size": 20
}

2. Get safety domain scores only

{
  "method": "get_vbp_scores",
  "quality_state": "CA",
  "vbp_domain": "safety",
  "size": 10
}

3. Get VBP scores for specific hospital

{
  "method": "get_vbp_scores",
  "quality_hospital_id": "050146"
}

Use Cases

• Payment Adjustment Analysis: VBP scores directly affect Medicare payments (+/- 2%)
• Quality Performance Benchmarking: Compare hospital performance across quality domains
• Value-Based Contracting: Identify high-performing hospitals for partnerships
• Market Analysis: Analyze quality-based payment adjustments in target markets

---

Method 13: get_hcahps_scores

Get Hospital Consumer Assessment of Healthcare Providers and Systems (HCAHPS) patient experience scores. HCAHPS is a standardized survey measuring patients' perspectives on hospital care.

Parameters

• method (required): Must be set to "get_hcahps_scores"
• quality_hospital_id (optional): CMS Certification Number (CCN) to lookup specific hospital
• quality_state (optional): State abbreviation to filter hospitals
• hcahps_measure (optional): Filter by specific HCAHPS measure (e.g., H_COMP_1_A_P for nurse communication, H_HSP_RATING_9_10 for hospital rating 9-10)
• size (optional): Number of results to return (default: 10)
• offset (optional): Starting result number for pagination (default: 0)

Response Format

{
  "total": 2,
  "hcahps_scores": [
    {
      "facility_id": "050002",
      "facility_name": "ST ROSE HOSPITAL",
      "state": "CA",
      "measure_id": "H_COMP_1_A_P",
      "measure_question": "Patients who reported that their nurses \"Always\" communicated well",
      "answer_description": "Nurses \"always\" communicated well",
      "answer_percent": "71",
      "star_rating": "Not Applicable",
      "linear_mean_value": "Not Applicable",
      "number_of_surveys": "380",
      "response_rate_percent": "21",
      "start_date": "01/01/2024",
      "end_date": "12/31/2024"
    }
  ]
}

Common HCAHPS Measures

• H_COMP_1_A_P: Nurses always communicated well
• H_COMP_2_A_P: Doctors always communicated well
• H_COMP_3_A_P: Staff always explained medicines
• H_COMP_5_A_P: Staff always helped with bathroom needs
• H_COMP_6_Y_P: Room always kept clean
• H_COMP_7_A_P: Area around room always kept quiet at night
• H_HSP_RATING_9_10: Hospital rating 9-10 (highest)
• H_RECMND_DY: Would definitely recommend hospital

Example Queries

1. Get all HCAHPS scores for a hospital

{
  "method": "get_hcahps_scores",
  "quality_hospital_id": "050146",
  "size": 50
}

2. Get nurse communication scores for California

{
  "method": "get_hcahps_scores",
  "quality_state": "CA",
  "hcahps_measure": "H_COMP_1_A_P",
  "size": 20
}

3. Get hospital recommendation rates

{
  "method": "get_hcahps_scores",
  "quality_state": "NY",
  "hcahps_measure": "H_RECMND_DY"
}

Use Cases

• Patient Experience Programs: Identify hospitals with low patient satisfaction for improvement programs
• Competitive Analysis: Compare patient experience scores across competing hospitals
• Quality Improvement Targeting: Focus on specific dimensions (communication, cleanliness, quiet, pain management)
• Star Rating Analysis: HCAHPS scores contribute 25% to overall hospital star rating

---

Method 14: get_asp_pricing

Get Average Sales Price (ASP) pricing for Medicare Part B drugs.

Parameters

• method (required): Must be set to "get_asp_pricing"
• hcpcs_code_asp (required): HCPCS code for Part B drug (e.g., "J9035" for Bevacizumab)
• quarter (optional): Quarter for ASP data (e.g., "2026Q1", "2025Q4"). Defaults to current quarter.

Response Fields

• hcpcs_code: HCPCS billing code
• short_descriptor: Drug name/description
• dosage: Dosage unit (e.g., "10 MG")
• payment_limit: Medicare payment limit (ASP × 1.06)
• asp_calculated: Calculated Average Sales Price
• medicare_reimbursement: Amount Medicare pays
• patient_coinsurance: Patient 20% coinsurance amount
• effective_period: Quarter and date range
• quarter: Data quarter (YYYYQN format)
• notes: Additional CMS notes
• found: Boolean indicating if drug was found

Example Requests

1. Get current ASP for Bevacizumab

{
  "method": "get_asp_pricing",
  "hcpcs_code_asp": "J9035"
}

2. Get ASP for specific quarter

{
  "method": "get_asp_pricing",
  "hcpcs_code_asp": "J0202",
  "quarter": "2026Q1"
}

Use Cases

• Reimbursement Analysis: Determine Medicare payment rates for Part B drugs
• Patient Cost Estimation: Calculate patient out-of-pocket costs (20% coinsurance)
• Revenue Forecasting: ASP × expected volume = revenue projections
• Price Transparency: Track Medicare pricing for physician-administered drugs

---

Method 15: get_asp_trend

Track ASP pricing changes over multiple quarters for trend analysis.

Parameters

• method (required): Must be set to "get_asp_trend"
• hcpcs_code_asp (required): HCPCS code for Part B drug
• start_quarter (required): Starting quarter (e.g., "2025Q1")
• end_quarter (required): Ending quarter (e.g., "2026Q1")

Response Fields

• hcpcs_code: HCPCS billing code
• drug_name: Drug name from first available quarter
• start_quarter: Requested start quarter
• end_quarter: Requested end quarter
• data_points: Number of quarters with available data
• trend_data: Array of quarterly data points with:
  • quarter: Quarter identifier
  • payment_limit: Medicare payment limit
  • asp_calculated: Average Sales Price
  • dosage: Dosage unit
  • dates: Quarter date range
• analysis: Statistical analysis:
  • min_price: Lowest price in range
  • max_price: Highest price in range
  • avg_price: Average price across quarters
  • price_change_percent: Percentage change from first to last quarter
  • price_volatility: Price variation as percentage

Example Requests

1. Track pricing over one year

{
  "method": "get_asp_trend",
  "hcpcs_code_asp": "J9035",
  "start_quarter": "2025Q1",
  "end_quarter": "2026Q1"
}

2. Long-term trend analysis

{
  "method": "get_asp_trend",
  "hcpcs_code_asp": "J0202",
  "start_quarter": "2024Q1",
  "end_quarter": "2026Q1"
}

Use Cases

• Price Trend Analysis: Identify drugs with increasing/decreasing prices
• Gross-to-Net Modeling: Track pricing trends for rebate strategy planning
• Budget Planning: Forecast future drug costs based on historical trends
• Market Access: Monitor pricing relative to competitors over time

---

Method 16: compare_asp_pricing

Compare ASP pricing across multiple drugs for competitive analysis.

Parameters

• method (required): Must be set to "compare_asp_pricing"
• hcpcs_codes (required): Array of HCPCS codes to compare (e.g., ["J9035", "J9299", "J0202"])
• quarter (optional): Quarter for comparison (e.g., "2026Q1"). Defaults to current quarter.

Response Fields

• quarter: Data quarter
• effective_period: Quarter date range
• drugs_compared: Number of drugs requested
• drugs_found: Number of drugs found in data
• comparisons: Array of drug data:
  • hcpcs_code: HCPCS billing code
  • drug_name: Drug description
  • dosage: Dosage unit
  • payment_limit: Medicare payment limit
  • asp_calculated: Average Sales Price
  • patient_coinsurance: Patient cost
  • notes: CMS notes
  • found: false if drug not found
• analysis: Comparison statistics:
  • lowest_price: Minimum price among drugs
  • highest_price: Maximum price among drugs
  • average_price: Mean price
  • price_range: Price spread (max - min)

Example Requests

1. Compare oncology drugs

{
  "method": "compare_asp_pricing",
  "hcpcs_codes": ["J9035", "J9299", "J9310"],
  "quarter": "2026Q1"
}

2. Compare biosimilars

{
  "method": "compare_asp_pricing",
  "hcpcs_codes": ["Q5117", "Q5119", "Q5120"]
}

Use Cases

• Competitive Pricing: Compare reimbursement rates across competing therapies
• Formulary Decisions: Evaluate cost differences for P&T committee decisions
• Biosimilar Analysis: Compare pricing between reference products and biosimilars
• Portfolio Management: Analyze pricing across drug portfolio

---

Method 17: get_formulary_trend

Track formulary policy changes over time to identify market access trends.

Parameters

• method (required): Must be set to "get_formulary_trend"
• start_month (required): Starting month in YYYYMM format (e.g., "202401")
• end_month (required): Ending month in YYYYMM format (e.g., "202512")
• drug_name (optional): Drug name to search (e.g., "Metformin")
• rxcui (optional): RxNorm Concept Unique Identifier
• trend_metric (optional): Specific metric to track ("prior_auth", "tier", "quantity_limit", "coverage", or "all"). Default: "all"

Response Fields

• drug_name: Name of drug analyzed
• rxcui: RxNorm identifier
• start_month / end_month: Analysis period
• data_points: Number of months with data
• trend_data: Monthly statistics array:
  • month: Month identifier (YYYYMM)
  • month_label: Human-readable format (YYYY-MM)
  • total_plans: Total number of plans evaluated
  • plans_with_coverage: Plans covering this drug
  • coverage_rate: Percentage of plans with coverage (0-1)
  • prior_auth_rate: Percentage requiring prior authorization (0-1)
  • quantity_limit_rate: Percentage with quantity limits (0-1)
  • avg_tier: Average formulary tier placement
• analysis: Trend analysis:
  • coverage_change: Change in coverage rate (%)
  • prior_auth_change: Change in prior auth requirements (%)
  • quantity_limit_change: Change in quantity limits (%)
  • avg_tier_change: Change in average tier
  • overall_assessment: AI assessment ("Access improving", "Access deteriorating", "Access stable")

Example Requests

1. Track prior authorization trends over 12 months

{
  "method": "get_formulary_trend",
  "start_month": "202401",
  "end_month": "202512",
  "drug_name": "Metformin"
}

2. Monitor tier changes for specific drug

{
  "method": "get_formulary_trend",
  "start_month": "202501",
  "end_month": "202512",
  "rxcui": "6809",
  "trend_metric": "tier"
}

3. Track market access deterioration

{
  "method": "get_formulary_trend",
  "start_month": "202401",
  "end_month": "202512",
  "drug_name": "Ozempic"
}

Example Response

{
  "drug_name": "Metformin",
  "rxcui": "6809",
  "start_month": "202401",
  "end_month": "202512",
  "data_points": 12,
  "trend_data": [
    {
      "month": "202401",
      "month_label": "2024-01",
      "total_plans": 3245,
      "plans_with_coverage": 3120,
      "coverage_rate": 0.961,
      "prior_auth_rate": 0.023,
      "quantity_limit_rate": 0.185,
      "avg_tier": 1.2
    },
    // ... 10 more months
    {
      "month": "202512",
      "month_label": "2025-12",
      "total_plans": 3289,
      "plans_with_coverage": 3145,
      "coverage_rate": 0.956,
      "prior_auth_rate": 0.038,
      "quantity_limit_rate": 0.221,
      "avg_tier": 1.3
    }
  ],
  "analysis": {
    "coverage_change": "-0.50%",
    "prior_auth_change": "+1.50%",
    "quantity_limit_change": "+3.60%",
    "avg_tier_change": "+0.10",
    "overall_assessment": "Access deteriorating - increased restrictions"
  }
}

Use Cases

• Market Access Monitoring: Track if your drug is getting harder to access over time
• Competitive Intelligence: Compare access trends across competing drugs
• P&T Strategy: Identify when formulary restrictions are tightening
• Budget Impact: Prior auth increases = higher administrative costs
• Patient Access Programs: Detect when patients may need more support
• Pricing Negotiations: Use access deterioration as leverage in rebate discussions
• Early Warning System: Catch restrictive trends before they impact sales

---

Data Sources

Hospital Quality Data

All hospital quality data comes from CMS Provider Data Catalog (data.cms.gov):

• Hospital General Information (xubh-q36u): Star ratings and hospital characteristics
• Unplanned Hospital Visits (632h-zaca): 30-day readmission rates
• Healthcare Associated Infections (77hc-ibv8): HAI/infection data
• Complications and Deaths (ynj2-r877): 30-day mortality rates
• Hospital Value-Based Purchasing (ypbt-wvdk): VBP performance scores
• Patient Survey HCAHPS (dgck-syfz): Patient experience scores

Data is updated quarterly by CMS and accessed via public API (no authentication required).

ASP Pricing Data

Medicare Part B Average Sales Price (ASP) pricing data:

• Source: CMS Medicare Part B ASP Pricing Files
• URL: https://www.cms.gov/medicare/payment/part-b-drugs/asp-pricing-files
• Update Frequency: Quarterly (January, April, July, October)
• Current Data: January 2026 (preliminary)
• Format: CSV files with HCPCS codes, payment limits, and dosage information
• Coverage: Physician-administered drugs (Part B), vaccines, immunizations
• Automation: GitHub Actions workflow checks for new quarters monthly
• Storage: data/asp/{QUARTER}_ASP_Pricing.csv.gz (dynamic quarter-based filenames)

ASP data is automatically downloaded, cleaned, compressed, and committed when new quarters are released.