# CMS Medicare Quality MCP (`andrew_avina/cms-medicare-mcp`) Actor This Apify actor exposes the Centers for Medicare & Medicaid Services (CMS) Hospital Quality data as a fully functional Model Context Protocol (MCP) server. It allows AI assistants, agents, and MCP-compatible clients to query real-time hospital quality ratings, safety scores, ... - **URL**: https://apify.com/andrew\_avina/cms-medicare-mcp.md - **Developed by:** [Andrew Avina](https://apify.com/andrew_avina) (community) - **Categories:** MCP servers, Business - **Stats:** 1 total users, 0 monthly users, 0.0% runs succeeded, NaN bookmarks - **User rating**: No ratings yet ## Pricing $3.00 / 1,000 result item returneds This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## CMS Medicare Quality Intelligence MCP Server This Apify actor exposes the Centers for Medicare & Medicaid Services (CMS) Hospital Quality data as a fully functional Model Context Protocol (MCP) server. It allows AI assistants, agents, and MCP-compatible clients to query real-time hospital quality ratings, safety scores, and facility information for every Medicare-certified hospital in the United States — no credentials required. --- ### What This Actor Does The CMS Provider Data Catalog contains quality ratings and performance metrics for approximately 5,000 Medicare-certified hospitals across the United States. This data includes overall star ratings (1–5), safety-of-care scores, readmission rates, patient experience results, and care effectiveness measures — all collected and published quarterly by CMS under the Hospital Compare program. For healthcare researchers, market analysts, compliance teams, and patient advocates, this dataset is one of the most authoritative public sources of hospital performance information available anywhere. This actor wraps the CMS Socrata API (`dataset xubh-q36u`) in a lightweight MCP server, making it instantly accessible to any LLM or agent framework that speaks MCP. When launched with `serveMcp: true`, it starts an HTTP server on port `4321` exposing three structured tools: hospital search by name or keyword, top-rated hospital lookup by state or nationally, and full hospital enumeration by state. In batch mode (`serveMcp: false`), it runs a one-time query and writes structured JSON records directly to the Apify dataset. **No API key. No registration. No rate-limit tokens to manage.** The CMS data API is fully open. --- ### MCP Tools Available Point your MCP client at `http://:4321` after setting `serveMcp: true`. #### 1. `cms_hospital_search` Searches CMS hospital records by facility name, city, or keyword. Returns matching hospitals with full quality metrics and contact information. | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `query` | string | Yes | Name, city, or keyword to search for (e.g. `"Cedars-Sinai"`, `"Boston"`) | | `state` | string | No | Two-letter state code to narrow results (e.g. `"CA"`, `"TX"`) | | `limit` | integer | No | Maximum number of results to return (default: `10`, max: `50`) | **Returns:** Array of hospital objects with quality ratings, address, phone, and facility metadata. **Example call:** ```json { "tool": "cms_hospital_search", "arguments": { "query": "Mayo Clinic", "state": "MN", "limit": 5 } } ```` *** #### 2. `cms_top_rated_hospitals` Returns hospitals with the highest CMS overall star ratings (4–5 stars), optionally filtered by state or hospital type. | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `state` | string | No | Two-letter state code (e.g. `"NY"`). Omit for nationwide results. | | `hospitalType` | string | No | Filter by type: `"Acute Care"`, `"Critical Access"`, `"Childrens"`, etc. | | `minRating` | integer | No | Minimum overall star rating (1–5, default: `4`) | | `limit` | integer | No | Maximum results (default: `10`, max: `50`) | **Returns:** Ranked list of high-performing hospitals with full metric breakdown. **Example call:** ```json { "tool": "cms_top_rated_hospitals", "arguments": { "state": "TX", "minRating": 5, "limit": 10 } } ``` *** #### 3. `cms_hospitals_by_state` Retrieves all Medicare-certified hospitals in a given state, with optional filters for rating and hospital type. | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `state` | string | Yes | Two-letter state code (e.g. `"FL"`) | | `minRating` | integer | No | Minimum overall star rating to include (1–5) | | `hospitalType` | string | No | Filter by hospital type string | | `limit` | integer | No | Maximum results (default: `25`, max: `100`) | **Returns:** Full list of hospitals in the state matching the specified filters. **Example call:** ```json { "tool": "cms_hospitals_by_state", "arguments": { "state": "FL", "minRating": 4, "limit": 25 } } ``` *** ### Batch Mode (Non-MCP) Set `serveMcp: false` in the actor input to run a single query and exit. The actor will execute the query, push results to the Apify dataset, and terminate — no persistent server is started. **Batch input fields:** | Field | Type | Description | |-------|------|-------------| | `serveMcp` | boolean | Set to `false` to enable batch mode | | `state` | string | Two-letter state code to query (e.g. `"CA"`) | | `query` | string | Keyword or facility name search term | | `hospitalType` | string | Filter by hospital type | | `minRating` | integer | Minimum overall CMS star rating (1–5) | | `limit` | integer | Maximum number of records to return | Results are written as structured JSON records to the default Apify dataset and can be exported as JSON, CSV, or XLSX from the Apify console. *** ### Data Source This actor queries the **CMS Provider Data Catalog** via the Socrata Open Data API. The specific dataset is the **Hospital General Information** dataset (`xubh-q36u`), maintained by the Centers for Medicare & Medicaid Services under the U.S. Department of Health and Human Services. The dataset covers all Medicare-certified inpatient hospitals in the United States — approximately 5,000 facilities. Quality metrics are updated quarterly and reflect the most recent Hospital Compare scoring cycle. The Socrata API endpoint is `https://data.cms.gov/resource/xubh-q36u.json` and requires no authentication for read access. *** ### Use Cases - **Hospital competitive analysis** — Compare star ratings, patient experience scores, and safety metrics across competing facilities in a market. - **Healthcare due diligence** — Evaluate acquisition targets or joint venture partners using objective CMS quality data. - **Regulatory compliance research** — Identify hospitals with poor safety-of-care or high readmission rates for compliance and audit prioritization. - **Patient safety research** — Analyze correlations between hospital ownership type, emergency service availability, and overall quality ratings. - **Healthcare market analysis** — Map hospital density, rating distribution, and service coverage gaps across states or regions. - **AI-assisted care navigation** — Power patient-facing agents that recommend highly rated facilities based on location and care needs. - **Grant and policy work** — Support public health research with structured, citable CMS data programmatically accessible via LLM tooling. *** ### Output Fields | Field | Type | Description | |-------|------|-------------| | `facility_id` | string | CMS Medicare provider number (unique identifier) | | `facility_name` | string | Official hospital name | | `address` | string | Street address | | `city` | string | City | | `state` | string | Two-letter state code | | `zip_code` | string | ZIP code | | `county` | string | County name | | `phone` | string | Facility phone number | | `hospital_type` | string | Hospital classification (e.g. `Acute Care Hospitals`) | | `ownership` | string | Ownership type (e.g. `Voluntary non-profit - Private`) | | `emergency_services` | boolean | Whether the facility offers emergency services | | `overall_rating` | integer | CMS overall star rating (1–5, or `null` if not rated) | | `safety_of_care` | string | Safety of care national comparison rating | | `readmission` | string | Readmission rate national comparison | | `patient_experience` | string | Patient experience national comparison | | `effectiveness_of_care` | string | Effectiveness of care national comparison | | `timeliness_of_care` | string | Timeliness of care national comparison | | `source` | string | Always `"CMS Provider Data Catalog"` | *** ### Integration Example **Claude Desktop `claude_desktop_config.json`:** ```json { "mcpServers": { "cms-medicare": { "url": "http://:4321", "transport": "http" } } } ``` **Sample agent conversation:** > **User:** Which hospitals in Arizona have a 5-star CMS rating and offer emergency services? > > **Assistant:** *(calls `cms_top_rated_hospitals` with state="AZ", minRating=5)* I found 4 hospitals in Arizona with a 5-star CMS overall rating that offer emergency services: Banner University Medical Center (Phoenix), Honor Health Scottsdale Osborn Medical Center, Mayo Clinic Hospital (Phoenix), and Chandler Regional Medical Center. All four score "Above the National Average" for patient experience and safety of care... *** *Data sourced from [CMS Provider Data Catalog](https://data.cms.gov/provider-data/). Updated quarterly by CMS. Coverage: All Medicare-certified hospitals in the United States.* # Actor input Schema ## `serveMcp` (type: `boolean`): Start MCP HTTP server on port 4321. ## `state` (type: `string`): 2-letter state code (e.g. 'CA', 'TX'). Filters results. ## `query` (type: `string`): Text search across facility names. ## `hospitalType` (type: `string`): e.g. 'Acute Care Hospitals', 'Critical Access Hospitals' ## `minRating` (type: `string`): Filter by minimum star rating (1-5). ## `limit` (type: `integer`): Max records to return (default 50). ## Actor input object example ```json { "serveMcp": false, "limit": 50 } ``` # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = {}; // Run the Actor and wait for it to finish const run = await client.actor("andrew_avina/cms-medicare-mcp").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = {} # Run the Actor and wait for it to finish run = client.actor("andrew_avina/cms-medicare-mcp").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{}' | apify call andrew_avina/cms-medicare-mcp --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=andrew_avina/cms-medicare-mcp", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "CMS Medicare Quality MCP", "description": "This Apify actor exposes the Centers for Medicare & Medicaid Services (CMS) Hospital Quality data as a fully functional Model Context Protocol (MCP) server. It allows AI assistants, agents, and MCP-compatible clients to query real-time hospital quality ratings, safety scores, ...", "version": "0.1", "x-build-id": "qVMZ1ZnXSr69wYTZL" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/andrew_avina~cms-medicare-mcp/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-andrew_avina-cms-medicare-mcp", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/andrew_avina~cms-medicare-mcp/runs": { "post": { "operationId": "runs-sync-andrew_avina-cms-medicare-mcp", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/andrew_avina~cms-medicare-mcp/run-sync": { "post": { "operationId": "run-sync-andrew_avina-cms-medicare-mcp", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "properties": { "serveMcp": { "title": "Serve MCP", "type": "boolean", "description": "Start MCP HTTP server on port 4321.", "default": false }, "state": { "title": "State Code", "type": "string", "description": "2-letter state code (e.g. 'CA', 'TX'). Filters results." }, "query": { "title": "Search Query", "type": "string", "description": "Text search across facility names." }, "hospitalType": { "title": "Hospital Type", "type": "string", "description": "e.g. 'Acute Care Hospitals', 'Critical Access Hospitals'" }, "minRating": { "title": "Minimum Overall Rating", "type": "string", "description": "Filter by minimum star rating (1-5)." }, "limit": { "title": "Result Limit", "minimum": 1, "maximum": 500, "type": "integer", "description": "Max records to return (default 50).", "default": 50 } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```