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>;
  }>;
}

Tool Definition Quality

Score is being calculated. Check back soon.

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