Skip to main content
Glama
openpharma-org

Medicare MCP Server

by openpharma-org
OverviewSchemaRelated ServersScoreDiscussions
JavaScript
Remote

medicare_info

Access Medicare data to analyze providers, hospitals, drug spending, formulary coverage, and quality metrics for healthcare research and decision-making.

Instructions

Unified tool for Medicare data operations: provider services, Part D prescribers, hospital data, spending information, hospital quality metrics, and ASP pricing. Use the method parameter to specify the operation type.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
methodYesThe operation to perform: - 'search_providers': Medicare Physician & Other Practitioners data - 'search_prescribers': Part D prescriber data - 'search_hospitals': Hospital utilization data - 'search_spending': Drug/service spending data - 'search_formulary': Part D formulary coverage - 'get_hospital_star_rating': Hospital overall quality star ratings (1-5) - 'get_readmission_rates': Hospital 30-day readmission rates by condition - 'get_hospital_infections': Hospital-acquired infections (HAI) data - 'get_mortality_rates': Hospital 30-day mortality rates - 'search_hospitals_by_quality': Find hospitals by quality metrics - 'compare_hospitals': Compare quality metrics across hospitals - 'get_vbp_scores': Hospital Value-Based Purchasing performance scores - 'get_hcahps_scores': Patient experience (HCAHPS) survey scores - 'get_asp_pricing': Medicare Part B ASP pricing data - 'get_asp_trend': ASP pricing trends over time - 'compare_asp_pricing': Compare ASP across drugs - 'get_formulary_trend': Track formulary changes over time (prior auth, tiers, coverage)
dataset_typeNoFor search_providers: Type of dataset to search. Options: - '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, or 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, or 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, or examine provider-level beneficiary characteristics and risk scores.
yearNoFor search_providers: Year of the dataset to query (2013 to latest available year, defaults to latest year).
hcpcs_codeNoFor search_providers: HCPCS code to search for (e.g., '99213' for established patient office visit).
provider_typeNoFor search_providers: Type of provider to search for (e.g., 'Cardiology', 'Podiatry', 'Family Practice').
geo_levelNoFor search_providers: Geographic level for filtering (e.g., 'National', 'State', 'County', 'ZIP').
geo_codeNoFor search_providers: Geographic code to filter by (e.g., 'CA' for California, '06037' for Los Angeles County).
place_of_serviceNoFor search_providers: Place of service code to filter by (e.g., 'F' for facility, 'O' for office, 'H' for hospital).
sizeNoNumber of results to return (default: 10 for search_providers, 25 for search_formulary, max: 5000).
offsetNoStarting result number for pagination (default: 0).
sort_byNoFor search_providers: Field to sort results by (e.g., 'Tot_Srvcs', 'Tot_Benes', 'Tot_Mdcr_Pymt_Amt').
sort_orderNoFor search_providers: Sort order ('asc' or 'desc', default: 'desc').
drug_nameNoFor search_prescribers: Drug name to search for - brand or generic (e.g., 'semaglutide', 'Ozempic', 'metformin'). Searches both brand and generic names.
prescriber_typeNoFor search_prescribers: Prescriber specialty (e.g., 'Endocrinology', 'Family Practice', 'Internal Medicine').
prescriber_npiNoFor search_prescribers: National Provider Identifier (NPI) of the prescriber.
stateNoFor search_prescribers, search_hospitals: State abbreviation (e.g., 'CA', 'TX', 'NY').
hospital_nameNoFor search_hospitals: Hospital name (partial match supported).
hospital_idNoFor search_hospitals: CMS Certification Number (CCN) or provider ID.
drg_codeNoFor search_hospitals (inpatient): Diagnosis Related Group (DRG) code.
spending_drug_nameNoFor search_spending: Drug name for spending analysis (brand or generic).
spending_typeNoFor search_spending: Type of spending data - 'part_d' (prescription drugs), 'part_b' (administered drugs). Default: 'part_d'.
formulary_drug_nameNoFor search_formulary: Drug name to search for (partial match supported, e.g., 'metformin', 'insulin'). At least one of formulary_drug_name or ndc_code is required.
ndc_codeNoFor search_formulary: NDC (National Drug Code) for exact drug identification (e.g., '00002143380'). At least one of drug_name or ndc_code is required.
tierNoFor search_formulary: Tier number to filter by (1=Preferred Generic, 2=Generic, 3=Preferred Brand, 4=Non-Preferred Brand, 5=Specialty, 6=Select Care).
requires_prior_authNoFor search_formulary: Filter by prior authorization requirement (true=requires PA, false=no PA required).
has_quantity_limitNoFor search_formulary: Filter by quantity limit (true=has limit, false=no limit).
has_step_therapyNoFor search_formulary: Filter by step therapy requirement (true=requires ST, false=no ST required).
plan_stateNoFor search_formulary: State abbreviation to filter plans (e.g., 'CA', 'TX', 'NY').
plan_idNoFor search_formulary: Medicare Part D plan ID to filter by specific plan.
quality_hospital_idNoFor hospital quality methods: CMS Certification Number (CCN) to lookup specific hospital (e.g., '050146').
quality_stateNoFor hospital quality methods: State abbreviation to filter hospitals (e.g., 'CA', 'TX', 'NY').
min_star_ratingNoFor search_hospitals_by_quality: Minimum star rating (1-5) to filter hospitals.
conditionNoFor get_readmission_rates/get_mortality_rates: Medical condition to filter by (e.g., 'heart_failure', 'pneumonia', 'heart_attack', 'copd', 'stroke').
infection_typeNoFor get_hospital_infections: Type of infection (e.g., 'CLABSI', 'CAUTI', 'SSI', 'CDIFF', 'MRSA').
metricsNoFor compare_hospitals: Array of metrics to compare (e.g., ['star_rating', 'readmission_rate', 'mortality_rate', 'infection_rate']).
hospital_idsNoFor compare_hospitals: Array of hospital CCN IDs to compare.
hcpcs_code_aspNoFor ASP pricing methods: HCPCS code for Part B drug (e.g., 'J9035' for Bevacizumab).
quarterNoFor get_asp_pricing: Quarter for ASP data (e.g., '2025Q1', '2024Q4').
start_quarterNoFor get_asp_trend: Starting quarter for trend analysis (e.g., '2023Q1').
end_quarterNoFor get_asp_trend: Ending quarter for trend analysis (e.g., '2025Q1').
hcpcs_codesNoFor compare_asp_pricing: Array of HCPCS codes to compare pricing.
hcahps_measureNoFor get_hcahps_scores: HCAHPS measure ID to filter by (e.g., 'H_COMP_1_A_P' for nurse communication, 'H_HSP_RATING_9_10' for hospital rating 9-10).
vbp_domainNoFor get_vbp_scores: VBP domain to filter by ('clinical_outcomes', 'person_community_engagement', 'safety', 'efficiency_cost_reduction', or 'all' for total performance score).
start_monthNoFor get_formulary_trend: Starting month in YYYYMM format (e.g., '202401' for January 2024).
end_monthNoFor get_formulary_trend: Ending month in YYYYMM format (e.g., '202512' for December 2025).
trend_metricNoFor get_formulary_trend: Metric to track ('prior_auth', 'tier', 'quantity_limit', 'coverage', or 'all'). Default: 'all'.

Implementation Reference

  • src/index.ts:118-407 (schema)
    Defines the complete Tool object for 'medicare_info' including name, detailed description, comprehensive input_schema with all parameters and methods, responseSchema, and usage examples.
    export const MEDICARE_INFO_TOOL: Tool = {
  name: "medicare_info",
  description: "Unified tool for Medicare data operations: provider services, Part D prescribers, hospital data, spending information, hospital quality metrics, and ASP pricing. Use the method parameter to specify the operation type.",
  input_schema: {
    type: "object",
    properties: {
      method: {
        type: "string",
        description: "The operation to perform:\n" +
          "- 'search_providers': Medicare Physician & Other Practitioners data\n" +
          "- 'search_prescribers': Part D prescriber data\n" +
          "- 'search_hospitals': Hospital utilization data\n" +
          "- 'search_spending': Drug/service spending data\n" +
          "- 'search_formulary': Part D formulary coverage\n" +
          "- 'get_hospital_star_rating': Hospital overall quality star ratings (1-5)\n" +
          "- 'get_readmission_rates': Hospital 30-day readmission rates by condition\n" +
          "- 'get_hospital_infections': Hospital-acquired infections (HAI) data\n" +
          "- 'get_mortality_rates': Hospital 30-day mortality rates\n" +
          "- 'search_hospitals_by_quality': Find hospitals by quality metrics\n" +
          "- 'compare_hospitals': Compare quality metrics across hospitals\n" +
          "- 'get_vbp_scores': Hospital Value-Based Purchasing performance scores\n" +
          "- 'get_hcahps_scores': Patient experience (HCAHPS) survey scores\n" +
          "- 'get_asp_pricing': Medicare Part B ASP pricing data\n" +
          "- 'get_asp_trend': ASP pricing trends over time\n" +
          "- 'compare_asp_pricing': Compare ASP across drugs\n" +
          "- 'get_formulary_trend': Track formulary changes over time (prior auth, tiers, coverage)"
      },
      dataset_type: {
        type: "string",
        description: "For search_providers: Type of dataset to search. Options:\n" +
          "- '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, or calculate per-capita/per-beneficiary rates by region.\n" +
          "- 'provider_and_service': Use when you need to analyze individual provider performance, track specific procedures by provider, calculate total procedures across providers, or study provider-level service patterns and outcomes.\n" +
          "- 'provider': Use when you need to analyze provider demographics, study provider participation in Medicare, understand provider practice patterns, or examine provider-level beneficiary characteristics and risk scores."
      },
      year: {
        type: "string",
        description: "For search_providers: Year of the dataset to query (2013 to latest available year, defaults to latest year)."
      },
      hcpcs_code: {
        type: "string",
        description: "For search_providers: HCPCS code to search for (e.g., '99213' for established patient office visit)."
      },
      provider_type: {
        type: "string",
        description: "For search_providers: Type of provider to search for (e.g., 'Cardiology', 'Podiatry', 'Family Practice')."
      },
      geo_level: {
        type: "string",
        description: "For search_providers: Geographic level for filtering (e.g., 'National', 'State', 'County', 'ZIP')."
      },
      geo_code: {
        type: "string",
        description: "For search_providers: Geographic code to filter by (e.g., 'CA' for California, '06037' for Los Angeles County)."
      },
      place_of_service: {
        type: "string",
        description: "For search_providers: Place of service code to filter by (e.g., 'F' for facility, 'O' for office, 'H' for hospital)."
      },
      size: {
        type: "number",
        description: "Number of results to return (default: 10 for search_providers, 25 for search_formulary, max: 5000)."
      },
      offset: {
        type: "number",
        description: "Starting result number for pagination (default: 0)."
      },
      sort_by: {
        type: "string",
        description: "For search_providers: Field to sort results by (e.g., 'Tot_Srvcs', 'Tot_Benes', 'Tot_Mdcr_Pymt_Amt')."
      },
      sort_order: {
        type: "string",
        description: "For search_providers: Sort order ('asc' or 'desc', default: 'desc')."
      },
      drug_name: {
        type: "string",
        description: "For search_prescribers: Drug name to search for - brand or generic (e.g., 'semaglutide', 'Ozempic', 'metformin'). Searches both brand and generic names."
      },
      prescriber_type: {
        type: "string",
        description: "For search_prescribers: Prescriber specialty (e.g., 'Endocrinology', 'Family Practice', 'Internal Medicine')."
      },
      prescriber_npi: {
        type: "string",
        description: "For search_prescribers: National Provider Identifier (NPI) of the prescriber."
      },
      state: {
        type: "string",
        description: "For search_prescribers, search_hospitals: State abbreviation (e.g., 'CA', 'TX', 'NY')."
      },
      hospital_name: {
        type: "string",
        description: "For search_hospitals: Hospital name (partial match supported)."
      },
      hospital_id: {
        type: "string",
        description: "For search_hospitals: CMS Certification Number (CCN) or provider ID."
      },
      drg_code: {
        type: "string",
        description: "For search_hospitals (inpatient): Diagnosis Related Group (DRG) code."
      },
      spending_drug_name: {
        type: "string",
        description: "For search_spending: Drug name for spending analysis (brand or generic)."
      },
      spending_type: {
        type: "string",
        description: "For search_spending: Type of spending data - 'part_d' (prescription drugs), 'part_b' (administered drugs). Default: 'part_d'."
      },
      formulary_drug_name: {
        type: "string",
        description: "For search_formulary: Drug name to search for (partial match supported, e.g., 'metformin', 'insulin'). At least one of formulary_drug_name or ndc_code is required."
      },
      ndc_code: {
        type: "string",
        description: "For search_formulary: NDC (National Drug Code) for exact drug identification (e.g., '00002143380'). At least one of drug_name or ndc_code is required."
      },
      tier: {
        type: "number",
        description: "For search_formulary: 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: {
        type: "boolean",
        description: "For search_formulary: Filter by prior authorization requirement (true=requires PA, false=no PA required)."
      },
      has_quantity_limit: {
        type: "boolean",
        description: "For search_formulary: Filter by quantity limit (true=has limit, false=no limit)."
      },
      has_step_therapy: {
        type: "boolean",
        description: "For search_formulary: Filter by step therapy requirement (true=requires ST, false=no ST required)."
      },
      plan_state: {
        type: "string",
        description: "For search_formulary: State abbreviation to filter plans (e.g., 'CA', 'TX', 'NY')."
      },
      plan_id: {
        type: "string",
        description: "For search_formulary: Medicare Part D plan ID to filter by specific plan."
      },
      quality_hospital_id: {
        type: "string",
        description: "For hospital quality methods: CMS Certification Number (CCN) to lookup specific hospital (e.g., '050146')."
      },
      quality_state: {
        type: "string",
        description: "For hospital quality methods: State abbreviation to filter hospitals (e.g., 'CA', 'TX', 'NY')."
      },
      min_star_rating: {
        type: "number",
        description: "For search_hospitals_by_quality: Minimum star rating (1-5) to filter hospitals."
      },
      condition: {
        type: "string",
        description: "For get_readmission_rates/get_mortality_rates: Medical condition to filter by (e.g., 'heart_failure', 'pneumonia', 'heart_attack', 'copd', 'stroke')."
      },
      infection_type: {
        type: "string",
        description: "For get_hospital_infections: Type of infection (e.g., 'CLABSI', 'CAUTI', 'SSI', 'CDIFF', 'MRSA')."
      },
      metrics: {
        type: "array",
        description: "For compare_hospitals: Array of metrics to compare (e.g., ['star_rating', 'readmission_rate', 'mortality_rate', 'infection_rate'])."
      },
      hospital_ids: {
        type: "array",
        description: "For compare_hospitals: Array of hospital CCN IDs to compare."
      },
      hcpcs_code_asp: {
        type: "string",
        description: "For ASP pricing methods: HCPCS code for Part B drug (e.g., 'J9035' for Bevacizumab)."
      },
      quarter: {
        type: "string",
        description: "For get_asp_pricing: Quarter for ASP data (e.g., '2025Q1', '2024Q4')."
      },
      start_quarter: {
        type: "string",
        description: "For get_asp_trend: Starting quarter for trend analysis (e.g., '2023Q1')."
      },
      end_quarter: {
        type: "string",
        description: "For get_asp_trend: Ending quarter for trend analysis (e.g., '2025Q1')."
      },
      hcpcs_codes: {
        type: "array",
        description: "For compare_asp_pricing: Array of HCPCS codes to compare pricing."
      },
      hcahps_measure: {
        type: "string",
        description: "For get_hcahps_scores: HCAHPS measure ID to filter by (e.g., 'H_COMP_1_A_P' for nurse communication, 'H_HSP_RATING_9_10' for hospital rating 9-10)."
      },
      vbp_domain: {
        type: "string",
        description: "For get_vbp_scores: VBP domain to filter by ('clinical_outcomes', 'person_community_engagement', 'safety', 'efficiency_cost_reduction', or 'all' for total performance score)."
      },
      start_month: {
        type: "string",
        description: "For get_formulary_trend: Starting month in YYYYMM format (e.g., '202401' for January 2024)."
      },
      end_month: {
        type: "string",
        description: "For get_formulary_trend: Ending month in YYYYMM format (e.g., '202512' for December 2025)."
      },
      trend_metric: {
        type: "string",
        description: "For get_formulary_trend: Metric to track ('prior_auth', 'tier', 'quantity_limit', 'coverage', or 'all'). Default: 'all'."
      }
    },
    required: ["method"]
  },
  responseSchema: {
    type: "object",
    properties: {
      total: {
        type: "number",
        description: "Total number of results found"
      },
      providers: { 
        type: "array",
        description: "List of Medicare providers matching the search criteria",
        items: {
          type: "object",
          properties: {
            npi: { type: "string", description: "Provider's National Provider Identifier (NPI)" },
            provider_name: { type: "string", description: "Provider's full name" },
            provider_type: { type: "string", description: "Provider's specialty or type of practice" },
            provider_address: { type: "string", description: "Provider's street address" },
            provider_city: { type: "string", description: "Provider's city" },
            provider_state: { type: "string", description: "Provider's state (2-letter abbreviation)" },
            provider_zip: { type: "string", description: "Provider's ZIP code" },
            provider_country: { type: "string", description: "Provider's country code (typically 'US')" },
            medicare_participating: { type: "string", description: "Whether the provider participates in Medicare ('Y' for yes, 'N' for no)" },
            total_hcpcs_codes: { type: "number", description: "Total number of unique HCPCS codes used by the provider" },
            total_beneficiaries: { type: "number", description: "Total number of unique Medicare beneficiaries served" },
            total_services: { type: "number", description: "Total number of services provided" },
            total_submitted_charges: { type: "number", description: "Total amount of submitted charges in dollars" },
            total_medicare_allowed: { type: "number", description: "Total amount allowed by Medicare in dollars" },
            total_medicare_payment: { type: "number", description: "Total amount paid by Medicare in dollars" },
            total_medicare_standardized: { type: "number", description: "Total standardized Medicare payment amount in dollars (adjusted for geographic differences)" },
            beneficiary_average_age: { type: "number", description: "Average age of beneficiaries served" },
            beneficiary_age_lt_65: { type: "number", description: "Number of beneficiaries under 65 years old" },
            beneficiary_age_65_74: { type: "number", description: "Number of beneficiaries aged 65-74" },
            beneficiary_age_75_84: { type: "number", description: "Number of beneficiaries aged 75-84" },
            beneficiary_age_gt_84: { type: "number", description: "Number of beneficiaries over 84 years old" },
            beneficiary_female_count: { type: "number", description: "Number of female beneficiaries" },
            beneficiary_male_count: { type: "number", description: "Number of male beneficiaries" },
            beneficiary_race_white: { type: "number", description: "Number of white beneficiaries" },
            beneficiary_race_black: { type: "number", description: "Number of black beneficiaries" },
            beneficiary_race_api: { type: "number", description: "Number of Asian/Pacific Islander beneficiaries" },
            beneficiary_race_hispanic: { type: "number", description: "Number of Hispanic beneficiaries" },
            beneficiary_race_native: { type: "number", description: "Number of Native American beneficiaries" },
            beneficiary_race_other: { type: "number", description: "Number of beneficiaries of other races" },
            beneficiary_dual_count: { type: "number", description: "Number of dual-eligible beneficiaries (eligible for both Medicare and Medicaid)" },
            beneficiary_non_dual_count: { type: "number", description: "Number of non-dual-eligible beneficiaries" },
            beneficiary_average_risk_score: { type: "number", description: "Average risk score of beneficiaries (higher scores indicate more complex medical conditions)" }
          }
        }
      }
    }
  },
  examples: [
    {
      name: 'Search for office visit codes by state (2023 data)',
      description: 'Search for office visit codes by state (2023 data)',
      input: { "dataset_type": "geography_and_service", "year": "2023", "hcpcs_code": "99213", "geo_level": "State", "geo_code": "CA", "size": 5, "sort_by": "Tot_Srvcs", "sort_order": "desc" },
      output: { "total": 5, "providers": [{ "npi": "1234567890", "provider_name": "Dr. Jane Smith", "provider_type": "Family Practice", "provider_address": "789 Health St", "provider_city": "Los Angeles", "provider_state": "CA", "provider_zip": "90001", "provider_country": "US", "medicare_participating": "Y", "total_hcpcs_codes": 10, "total_beneficiaries": 100, "total_services": 500, "total_submitted_charges": 50000, "total_medicare_allowed": 40000, "total_medicare_payment": 35000, "total_medicare_standardized": 34000, "beneficiary_average_age": 70, "beneficiary_age_lt_65": 20, "beneficiary_age_65_74": 30, "beneficiary_age_75_84": 25, "beneficiary_age_gt_84": 25, "beneficiary_female_count": 55, "beneficiary_male_count": 45, "beneficiary_race_white": 60, "beneficiary_race_black": 10, "beneficiary_race_api": 15, "beneficiary_race_hispanic": 10, "beneficiary_race_native": 2, "beneficiary_race_other": 3, "beneficiary_dual_count": 15, "beneficiary_non_dual_count": 85, "beneficiary_average_risk_score": 1.2 }] }
    },
    {
      name: 'Search for providers by specialty with pagination',
      description: 'Search for providers by specialty with pagination',
      input: { "dataset_type": "provider", "provider_type": "Podiatry", "geo_level": "State", "geo_code": "NY", "size": 10, "offset": 20, "sort_by": "Tot_Mdcr_Pymt_Amt", "sort_order": "desc" },
      output: { "total": 10, "providers": [{ "npi": "0987654321", "provider_name": "Dr. John Doe", "provider_type": "Podiatry", "provider_address": "123 Foot Ave", "provider_city": "New York", "provider_state": "NY", "provider_zip": "10001", "provider_country": "US", "medicare_participating": "Y", "total_hcpcs_codes": 8, "total_beneficiaries": 80, "total_services": 400, "total_submitted_charges": 40000, "total_medicare_allowed": 32000, "total_medicare_payment": 28000, "total_medicare_standardized": 27000, "beneficiary_average_age": 65, "beneficiary_age_lt_65": 15, "beneficiary_age_65_74": 25, "beneficiary_age_75_84": 20, "beneficiary_age_gt_84": 20, "beneficiary_female_count": 45, "beneficiary_male_count": 35, "beneficiary_race_white": 50, "beneficiary_race_black": 8, "beneficiary_race_api": 12, "beneficiary_race_hispanic": 8, "beneficiary_race_native": 1, "beneficiary_race_other": 1, "beneficiary_dual_count": 10, "beneficiary_non_dual_count": 70, "beneficiary_average_risk_score": 1.1 }] }
    },
    {
      name: 'Search for specific procedure by place of service',
      description: 'Search for specific procedure by place of service',
      input: { "dataset_type": "provider_and_service", "hcpcs_code": "45378", "place_of_service": "O", "size": 5, "sort_by": "Tot_Srvcs", "sort_order": "desc" },
      output: { "total": 5, "providers": [{ "npi": "1122334455", "provider_name": "Dr. Alice Johnson", "provider_type": "Gastroenterology", "provider_address": "456 Digestive Blvd", "provider_city": "Chicago", "provider_state": "IL", "provider_zip": "60601", "provider_country": "US", "medicare_participating": "Y", "total_hcpcs_codes": 12, "total_beneficiaries": 120, "total_services": 600, "total_submitted_charges": 60000, "total_medicare_allowed": 48000, "total_medicare_payment": 42000, "total_medicare_standardized": 41000, "beneficiary_average_age": 68, "beneficiary_age_lt_65": 25, "beneficiary_age_65_74": 35, "beneficiary_age_75_84": 30, "beneficiary_age_gt_84": 30, "beneficiary_female_count": 60, "beneficiary_male_count": 60, "beneficiary_race_white": 70, "beneficiary_race_black": 15, "beneficiary_race_api": 20, "beneficiary_race_hispanic": 15, "beneficiary_race_native": 3, "beneficiary_race_other": 3, "beneficiary_dual_count": 20, "beneficiary_non_dual_count": 100, "beneficiary_average_risk_score": 1.3 }] }
    },
    {
      name: 'Get total knee replacement procedures in California (2023)',
      description: 'Search for all providers performing knee replacements (HCPCS 27447) in California, sorted by total services to get the top 100 providers',
      input: { "dataset_type": "provider_and_service", "year": "2023", "hcpcs_code": "27447", "geo_level": "State", "geo_code": "CA", "size": 100, "sort_by": "Tot_Srvcs", "sort_order": "desc" },
      output: { "total": 100, "providers": [{ "npi": "1234567890", "provider_name": "Dr. John Smith", "provider_type": "Orthopedic Surgery", "provider_address": "123 Medical Center Dr", "provider_city": "Los Angeles", "provider_state": "CA", "provider_zip": "90024", "provider_country": "US", "medicare_participating": "Y", "total_hcpcs_codes": 15, "total_beneficiaries": 95, "total_services": 120, "total_submitted_charges": 1200000, "total_medicare_allowed": 960000, "total_medicare_payment": 840000, "total_medicare_standardized": 820000, "beneficiary_average_age": 72, "beneficiary_age_lt_65": 15, "beneficiary_age_65_74": 35, "beneficiary_age_75_84": 30, "beneficiary_age_gt_84": 20, "beneficiary_female_count": 65, "beneficiary_male_count": 30, "beneficiary_race_white": 70, "beneficiary_race_black": 5, "beneficiary_race_api": 10, "beneficiary_race_hispanic": 10, "beneficiary_race_native": 1, "beneficiary_race_other": 4, "beneficiary_dual_count": 10, "beneficiary_non_dual_count": 85, "beneficiary_average_risk_score": 1.2 }], "total_services": 4958 }
    }
  ]
};
  • src/index.ts:2150-2350 (handler)
    Primary handler for medicare_info tool execution within MCP CallToolRequestSchema. Parses input.method and dispatches to 17 specialized helper functions (search_providers, search_prescribers, etc.) based on the method parameter.
    switch (toolName) {
  case 'medicare_info': {
    const method = (args as any)?.method;

    switch (method) {
      case 'search_providers': {
        const result = await searchMedicare(
          (args as any)?.dataset_type,
          (args as any)?.year,
          (args as any)?.hcpcs_code,
          (args as any)?.geo_level,
          (args as any)?.geo_code,
          (args as any)?.place_of_service,
          (args as any)?.size,
          (args as any)?.offset,
          (args as any)?.text_search,
          (args as any)?.sort,
          (args as any)?.provider_type
        );
        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }], isError: false };
      }

      case 'search_prescribers': {
        const result = await searchPrescribers(
          (args as any)?.drug_name,
          (args as any)?.prescriber_npi,
          (args as any)?.prescriber_type,
          (args as any)?.state,
          (args as any)?.size,
          (args as any)?.offset,
          (args as any)?.sort
        );
        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }], isError: false };
      }

      case 'search_hospitals': {
        const result = await searchHospitals(
          (args as any)?.hospital_name,
          (args as any)?.hospital_id,
          (args as any)?.state,
          (args as any)?.city,
          (args as any)?.drg_code,
          (args as any)?.size,
          (args as any)?.offset,
          (args as any)?.sort
        );
        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }], isError: false };
      }

      case 'search_spending': {
        const result = await searchSpending(
          (args as any)?.spending_drug_name,
          (args as any)?.spending_type,
          (args as any)?.year,
          (args as any)?.size,
          (args as any)?.offset,
          (args as any)?.sort
        );
        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }], isError: false };
      }

      case 'search_formulary': {
        const result = await searchFormulary(
          (args as any)?.formulary_drug_name,
          (args as any)?.ndc_code,
          (args as any)?.tier,
          (args as any)?.requires_prior_auth,
          (args as any)?.has_quantity_limit,
          (args as any)?.has_step_therapy,
          (args as any)?.plan_state,
          (args as any)?.plan_id,
          (args as any)?.size,
          (args as any)?.offset
        );
        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }], isError: false };
      }

      case 'get_hospital_star_rating': {
        const result = await getHospitalStarRating(
          (args as any)?.quality_hospital_id,
          (args as any)?.quality_state,
          (args as any)?.size,
          (args as any)?.offset
        );
        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }], isError: false };
      }

      case 'get_readmission_rates': {
        const result = await getReadmissionRates(
          (args as any)?.quality_hospital_id,
          (args as any)?.quality_state,
          (args as any)?.condition,
          (args as any)?.size,
          (args as any)?.offset
        );
        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }], isError: false };
      }

      case 'get_hospital_infections': {
        const result = await getHospitalInfections(
          (args as any)?.quality_hospital_id,
          (args as any)?.quality_state,
          (args as any)?.infection_type,
          (args as any)?.size,
          (args as any)?.offset
        );
        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }], isError: false };
      }

      case 'get_mortality_rates': {
        const result = await getMortalityRates(
          (args as any)?.quality_hospital_id,
          (args as any)?.quality_state,
          (args as any)?.condition,
          (args as any)?.size,
          (args as any)?.offset
        );
        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }], isError: false };
      }

      case 'search_hospitals_by_quality': {
        const result = await searchHospitalsByQuality(
          (args as any)?.quality_state,
          (args as any)?.min_star_rating,
          (args as any)?.size,
          (args as any)?.offset
        );
        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }], isError: false };
      }

      case 'compare_hospitals': {
        const result = await compareHospitals(
          (args as any)?.hospital_ids,
          (args as any)?.metrics,
          (args as any)?.size
        );
        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }], isError: false };
      }

      case 'get_vbp_scores': {
        const result = await getVbpScores(
          (args as any)?.quality_hospital_id,
          (args as any)?.quality_state,
          (args as any)?.vbp_domain,
          (args as any)?.size,
          (args as any)?.offset
        );
        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }], isError: false };
      }

      case 'get_hcahps_scores': {
        const result = await getHcahpsScores(
          (args as any)?.quality_hospital_id,
          (args as any)?.quality_state,
          (args as any)?.hcahps_measure,
          (args as any)?.size,
          (args as any)?.offset
        );
        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }], isError: false };
      }

      case 'get_asp_pricing': {
        const result = await getAspPricing(
          (args as any)?.hcpcs_code_asp,
          (args as any)?.quarter
        );
        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }], isError: false };
      }

      case 'get_asp_trend': {
        const result = await getAspTrend(
          (args as any)?.hcpcs_code_asp,
          (args as any)?.start_quarter,
          (args as any)?.end_quarter
        );
        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }], isError: false };
      }

      case 'compare_asp_pricing': {
        const result = await compareAspPricing(
          (args as any)?.hcpcs_codes,
          (args as any)?.quarter
        );
        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }], isError: false };
      }

      case 'get_formulary_trend': {
        const result = await getFormularyTrend(
          (args as any)?.start_month,
          (args as any)?.end_month,
          (args as any)?.drug_name,
          (args as any)?.rxcui,
          (args as any)?.trend_metric
        );
        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }], isError: false };
      }

      default:
        throw new McpError(-32602, `Unknown method: ${method}. Valid methods: search_providers, search_prescribers, search_hospitals, search_spending, search_formulary, get_hospital_star_rating, get_readmission_rates, get_hospital_infections, get_mortality_rates, search_hospitals_by_quality, compare_hospitals, get_vbp_scores, get_hcahps_scores, get_asp_pricing, get_asp_trend, compare_asp_pricing, get_formulary_trend`);
    }
  }
  • src/index.ts:2136-2144 (registration)
    Registers the medicare_info tool with the MCP server via ListToolsRequestSchema handler, exposing name, description, and input schema.
    server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [
    {
      name: MEDICARE_INFO_TOOL.name,
      description: MEDICARE_INFO_TOOL.description,
      inputSchema: MEDICARE_INFO_TOOL.input_schema
    }
  ]
}));
  • src/index.ts:502-678 (helper)
    Core helper function implementing 'search_providers' method: queries CMS Medicare Physician datasets (3 types), supports geographic/provider/service filtering, HCPCS codes, sorting/pagination, returns standardized provider profiles.
    async function searchMedicare(
  dataset_type: string = "geography_and_service",
  year?: string,
  hcpcs_code?: string,
  geo_level?: string,
  geo_code?: string,
  place_of_service?: string,
  size: number = 10,
  offset: number = 0,
  text_search?: string,
  sort?: { field: string; direction: 'asc' | 'desc' },
  provider_type?: string
) {
  let datasetVersionId: string;
  let selectedYear: string;
  if (dataset_type === "geography_and_service") {
    selectedYear = year || getLatestYear(versionMapGeography);
    datasetVersionId = versionMapGeography[selectedYear];
  } else if (dataset_type === "provider_and_service") {
    selectedYear = year || getLatestYear(versionMapProviderAndService);
    datasetVersionId = versionMapProviderAndService[selectedYear];
  } else if (dataset_type === "provider") {
    selectedYear = year || getLatestYear(versionMapProvider);
    datasetVersionId = versionMapProvider[selectedYear];
  } else {
    throw new Error(`Invalid dataset_type: ${dataset_type}`);
  }

  if (!datasetVersionId) {
    throw new Error(`Invalid year specified: ${selectedYear} for dataset_type: ${dataset_type}`);
  }

  const query = new URLSearchParams({
    size: Math.min(size, 5000).toString(),
    offset: offset.toString()
  });

  // Add filters using the CMS API filter syntax
  if (geo_level && geo_code) {
    if (dataset_type === "geography_and_service") {
      query.append("filter[Rndrng_Prvdr_Geo_Lvl]", geo_level);
      query.append("filter[Rndrng_Prvdr_Geo_Cd]", geo_code);
    } else {
      // For provider_and_service and provider datasets
      if (geo_level === "State") {
        query.append("filter[Rndrng_Prvdr_State_Abrvtn]", geo_code);
      } else if (geo_level === "County") {
        query.append("filter[Rndrng_Prvdr_State_FIPS]", geo_code);
      } else if (geo_level === "ZIP") {
        query.append("filter[Rndrng_Prvdr_Zip5]", geo_code);
      }
    }
  }

  if (hcpcs_code && (dataset_type === "geography_and_service" || dataset_type === "provider_and_service")) {
    query.append("filter[HCPCS_Cd]", hcpcs_code);
  }

  if (place_of_service && (dataset_type === "geography_and_service" || dataset_type === "provider_and_service")) {
    query.append("filter[Place_Of_Srvc]", place_of_service);
  }

  if (provider_type && (dataset_type === "provider_and_service" || dataset_type === "provider")) {
    query.append("filter[Rndrng_Prvdr_Type]", provider_type);
  }

  if (text_search) {
    // Add text search filter for relevant fields based on dataset type
    if (dataset_type === "provider" || dataset_type === "provider_and_service") {
      query.append("Rndrng_Prvdr_Last_Org_Name", text_search);
      query.append("Rndrng_Prvdr_First_Name", text_search);
    }
    if (dataset_type === "geography_and_service" || dataset_type === "provider_and_service") {
      query.append("HCPCS_Desc", text_search);
    }
  }

  if (sort) {
    query.append("sort", `${sort.direction === 'desc' ? '-' : ''}${sort.field}`);
  }

  const url = `https://data.cms.gov/data-api/v1/dataset/${datasetVersionId}/data?${query.toString()}`;

  const response = await fetch(url);
  if (!response.ok) {
    throw new Error(`HTTP error! status: ${response.status}`);
  }
  const data = await response.json() as (MedicareProviderGeographyResponse[] | MedicareProviderIndividualResponse[] | MedicareProviderResponse[]);

  return {
    total: data.length,
    providers: data.map((item) => {
      if (dataset_type === "provider") {
        const providerItem = item as MedicareProviderResponse;
        return {
          npi: providerItem.Rndrng_NPI,
          provider_name: `${providerItem.Rndrng_Prvdr_Last_Org_Name}, ${providerItem.Rndrng_Prvdr_First_Name}${providerItem.Rndrng_Prvdr_MI ? ` ${providerItem.Rndrng_Prvdr_MI}` : ''}`,
          provider_type: providerItem.Rndrng_Prvdr_Type,
          provider_address: providerItem.Rndrng_Prvdr_St1,
          provider_city: providerItem.Rndrng_Prvdr_City,
          provider_state: providerItem.Rndrng_Prvdr_State_Abrvtn,
          provider_zip: providerItem.Rndrng_Prvdr_Zip5,
          provider_country: providerItem.Rndrng_Prvdr_Cntry,
          medicare_participating: providerItem.Rndrng_Prvdr_Mdcr_Prtcptg_Ind,
          total_hcpcs_codes: parseInt(providerItem.Tot_HCPCS_Cds),
          total_beneficiaries: providerItem.Tot_Benes,
          total_services: providerItem.Tot_Srvcs,
          total_submitted_charges: providerItem.Tot_Sbmtd_Chrg,
          total_medicare_allowed: providerItem.Tot_Mdcr_Alowd_Amt,
          total_medicare_payment: providerItem.Tot_Mdcr_Pymt_Amt,
          total_medicare_standardized: providerItem.Tot_Mdcr_Stdzd_Amt,
          beneficiary_average_age: providerItem.Bene_Avg_Age,
          beneficiary_age_lt_65: providerItem.Bene_Age_LT_65_Cnt,
          beneficiary_age_65_74: providerItem.Bene_Age_65_74_Cnt,
          beneficiary_age_75_84: providerItem.Bene_Age_75_84_Cnt,
          beneficiary_age_gt_84: providerItem.Bene_Age_GT_84_Cnt,
          beneficiary_female_count: providerItem.Bene_Feml_Cnt,
          beneficiary_male_count: providerItem.Bene_Male_Cnt,
          beneficiary_race_white: providerItem.Bene_Race_Wht_Cnt,
          beneficiary_race_black: providerItem.Bene_Race_Black_Cnt,
          beneficiary_race_api: providerItem.Bene_Race_API_Cnt,
          beneficiary_race_hispanic: providerItem.Bene_Race_Hspnc_Cnt,
          beneficiary_race_native: providerItem.Bene_Race_NatInd_Cnt,
          beneficiary_race_other: providerItem.Bene_Race_Othr_Cnt,
          beneficiary_dual_count: providerItem.Bene_Dual_Cnt,
          beneficiary_non_dual_count: providerItem.Bene_Ndual_Cnt,
          beneficiary_average_risk_score: providerItem.Bene_Avg_Risk_Scre
        };
      }

      if (dataset_type === "geography_and_service") {
        const geoItem = item as MedicareProviderGeographyResponse;
        return {
          hcpcs_code: geoItem.HCPCS_Cd,
          hcpcs_desc: geoItem.HCPCS_Desc,
          hcpcs_drug_ind: geoItem.HCPCS_Drug_Ind,
          place_of_service: geoItem.Place_Of_Srvc,
          total_beneficiaries: geoItem.Tot_Benes,
          total_services: geoItem.Tot_Srvcs,
          total_beneficiary_days: geoItem.Tot_Bene_Day_Srvcs,
          avg_submitted_charge: geoItem.Avg_Sbmtd_Chrg,
          avg_medicare_allowed: geoItem.Avg_Mdcr_Alowd_Amt,
          avg_medicare_payment: geoItem.Avg_Mdcr_Pymt_Amt,
          avg_medicare_standardized: geoItem.Avg_Mdcr_Stdzd_Amt,
          geo_level: geoItem.Rndrng_Prvdr_Geo_Lvl,
          geo_code: geoItem.Rndrng_Prvdr_Geo_Cd,
          geo_desc: geoItem.Rndrng_Prvdr_Geo_Desc,
          total_providers: geoItem.Tot_Rndrng_Prvdrs
        };
      } else {
        const providerItem = item as MedicareProviderIndividualResponse;
        return {
          hcpcs_code: providerItem.HCPCS_Cd,
          hcpcs_desc: providerItem.HCPCS_Desc,
          hcpcs_drug_ind: providerItem.HCPCS_Drug_Ind,
          place_of_service: providerItem.Place_Of_Srvc,
          total_beneficiaries: providerItem.Tot_Benes,
          total_services: providerItem.Tot_Srvcs,
          total_beneficiary_days: providerItem.Tot_Bene_Day_Srvcs,
          avg_submitted_charge: providerItem.Avg_Sbmtd_Chrg,
          avg_medicare_allowed: providerItem.Avg_Mdcr_Alowd_Amt,
          avg_medicare_payment: providerItem.Avg_Mdcr_Pymt_Amt,
          avg_medicare_standardized: providerItem.Avg_Mdcr_Stdzd_Amt,
          npi: providerItem.Rndrng_NPI,
          provider_name: `${providerItem.Rndrng_Prvdr_Last_Org_Name}, ${providerItem.Rndrng_Prvdr_First_Name}${providerItem.Rndrng_Prvdr_MI ? ` ${providerItem.Rndrng_Prvdr_MI}` : ''}`,
          provider_type: providerItem.Rndrng_Prvdr_Type,
          provider_address: providerItem.Rndrng_Prvdr_St1,
          provider_city: providerItem.Rndrng_Prvdr_City,
          provider_state: providerItem.Rndrng_Prvdr_State_Abrvtn,
          provider_zip: providerItem.Rndrng_Prvdr_Zip5,
          provider_country: providerItem.Rndrng_Prvdr_Cntry,
          medicare_participating: providerItem.Rndrng_Prvdr_Mdcr_Prtcptg_Ind
        };
      }
    })
  };
}
  • src/types.ts:1-39 (schema)
    TypeScript interface definition for Tool objects, used to type the MEDICARE_INFO_TOOL export and ensure schema structure compliance.
    export interface Tool {
  name: string;
  description: string;
  input_schema: {
    type: string;
    properties: {
      [key: string]: {
        type: string;
        description: string;
        default?: any;
      };
    };
    required: string[];
  };
  responseSchema: {
    type: string;
    properties: {
      [key: string]: {
        type: string;
        description: string;
        items?: {
          type: string;
          properties: {
            [key: string]: {
              type: string;
              description: string;
            };
          };
        };
      };
    };
  };
  examples: Array<{
    name: string;
    description: string;
    input: Record<string, any>;
    output: Record<string, any>;
  }>;
}
Install Server

Other Tools

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/openpharma-org/medicare-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server