Tutorial: CMS Open Data (Medicare & Medicaid)

Health

Data source: CMS Provider Data Catalog (data.cms.gov)

Overview

CMS Open Data (Medicare & Medicaid) wraps CMS Provider Data Catalog (data.cms.gov), handling authentication, pagination, and rate limits for you. This tutorial covers all 5 tools with working code examples you can copy and run.

Prerequisites

Sign up at https://context.gnist.ai/signup for a free API key (100 calls/day).
Choose your integration method: MCP protocol or REST API.

Connect via MCP

Add to your MCP client config (Claude Desktop, Cursor, etc.):

MCP Config

{
  "mcpServers": {
    "gnist-cms": {
      "url": "https://context.gnist.ai/mcp/cms/",
      "headers": {
        "Gnist-API-Key": "YOUR_API_KEY"
      }
    }
  }
}

Tools (5)

`search_hospitals`

Search US hospitals by name, city, or state using CMS General Information data. Returns hospital name, address, type, ownership, emergency services availability, and overall CMS star rating. Data is sourced from the CMS Provider Data Catalog and is updated quarterly. Args: query: Free-text search matched against hospital name and city. state: Two-letter US state code to filter results. limit: Maximum hospitals to return (1-50, default 10). Returns: List of hospitals with name, location, type, ownership, and star rating.

Parameter	Type	Required	Description
`query`	any	optional	Free-text search string matched against hospital name and city (e.g. "Mayo Clinic", "Houston").
`state`	any	optional	Two-letter US state code to filter results (e.g. "CA", "NY", "TX").
`limit`	integer	optional	Maximum number of hospitals to return (1-50, default 10). (default: `10`)

curl -X POST "https://context.gnist.ai/mcp/cms/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "search_hospitals", "arguments": {"query": "Mayo Clinic"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/cms/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'query': 'Mayo Clinic'}, 'name': 'search_hospitals'}},
)
print(resp.json())

`get_hospital_quality`

Get quality measures for a specific hospital by its CMS facility ID. Returns clinical quality scores, patient safety measures, patient experience ratings, and how each measure compares to national benchmarks. Includes measure start/end dates and any applicable footnotes. Args: facility_id: 6-digit CMS facility ID (e.g. "050324"). Returns: Quality measures with scores, national comparison, and date ranges.

Parameter	Type	Required	Description
`facility_id`	string	required	6-digit CMS facility ID for the hospital (e.g. "050324"). Use search_hospitals to find IDs.

curl -X POST "https://context.gnist.ai/mcp/cms/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "get_hospital_quality", "arguments": {"facility_id": "050324"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/cms/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'facility_id': '050324'},
            'name': 'get_hospital_quality'}},
)
print(resp.json())

`search_providers`

Search doctors and clinicians in the NPPES NPI Registry. Returns provider name, credentials, NPI number, primary specialty, practice address, and phone number. At least name or specialty must be provided; state alone is not sufficient. Args: name: Provider last name. state: Two-letter US state code. specialty: Medical specialty (e.g. "Internal Medicine", "Cardiology"). limit: Maximum providers to return (1-50, default 10). Returns: Provider list with NPI, name, specialty, credentials, and location.

Parameter	Type	Required	Description
`name`	any	optional	Provider last name or organization name to search (e.g. "Smith", "Cleveland Clinic").
`state`	any	optional	Two-letter US state code (e.g. "OH", "FL").
`specialty`	any	optional	Medical specialty to filter by (e.g. "Internal Medicine", "Cardiology").
`limit`	integer	optional	Maximum number of providers to return (1-50, default 10). (default: `10`)

curl -X POST "https://context.gnist.ai/mcp/cms/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "search_providers", "arguments": {"name": "Smith"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/cms/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'name': 'Smith'}, 'name': 'search_providers'}},
)
print(resp.json())

`get_spending`

Get Medicare spending per beneficiary for a hospital. Returns average Medicare spending per patient episode for the facility compared to the national average. This metric reflects total payments across the care episode — hospital, post-acute, and other services. Args: facility_id: 6-digit CMS facility ID (e.g. "050324"). Returns: Spending per beneficiary, national average, and measurement period.

Parameter	Type	Required	Description
`facility_id`	string	required	6-digit CMS facility ID for the hospital (e.g. "050324"). Use search_hospitals to find IDs.

curl -X POST "https://context.gnist.ai/mcp/cms/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "get_spending", "arguments": {"facility_id": "050324"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/cms/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'facility_id': '050324'}, 'name': 'get_spending'}},
)
print(resp.json())

`report_feedback`

Report a bug, feature request, or general feedback for this data source. Use this when something doesn't work as expected, when you'd like a new feature, or when you have suggestions for improvement. Args: feedback: Describe the issue or suggestion. feedback_type: One of 'bug', 'feature_request', or 'general'.

Parameter	Type	Required	Description
`feedback`	string	required
`feedback_type`	string	optional	(default: `general`)

curl -X POST "https://context.gnist.ai/mcp/cms/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "report_feedback", "arguments": {"feedback": "example"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/cms/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'feedback': 'example'}, 'name': 'report_feedback'}},
)
print(resp.json())

Common Patterns

Search then retrieve
Use search_hospitals to find items, then get_hospital_quality to get full details. This two-step pattern is common for exploring data before drilling down.

Pagination
Several tools support limit, offset, or page parameters. Start with small limits during development, then increase for production queries.

FAQ

What data does CMS Open Data (Medicare & Medicaid) provide?

US hospital quality ratings, provider/clinician search, and Medicare spending data from the CMS Provider Data Catalog — search hospitals by name or state, get quality measures, find Medicare-enrolled doctors, and compare spending per beneficiary. It exposes 5 tools: search_hospitals, get_hospital_quality, search_providers, get_spending, report_feedback.

What do I need to get started?

A Gnist API key (free tier: 100 calls/day). Sign up at https://context.gnist.ai/signup.

What format does the CMS Open Data (Medicare & Medicaid) API return?

JSON, via either MCP protocol (JSON-RPC 2.0) or REST API.