CMS Data.gov MCP Server

A Model Context Protocol (MCP) server that provides Claude and other MCP clients with direct access to CMS (Centers for Medicare & Medicaid Services) healthcare data from data.cms.gov.

Overview

This MCP server enables AI assistants to:

• Search and discover CMS healthcare datasets

• Query dataset records with filters and pagination

• Get dataset statistics and metadata

• Obtain CSV download links for large-scale analysis

Perfect for healthcare analytics workflows, especially when working with LEJR (Lower Extremity Joint Replacement) analyses, provider enrollment data, hospital quality metrics, and other CMS datasets.

Related MCP server: ClinicalTrials MCP Server

Features

Five Core Tools

1. cms_search_datasets - Find datasets by keyword or theme

2. cms_get_dataset - Get detailed dataset information

3. cms_query_dataset - Query data with filters (up to 5000 rows)

4. cms_get_dataset_stats - Get row counts and column info

5. cms_get_csv_link - Get CSV download URL for Athena

Resource Templates

• cms://datasets - Browse all available CMS datasets

• cms://dataset/{id} - Access specific dataset metadata

• cms://csv/{id} - Get CSV download link

Installation

Prerequisites

• Node.js 18 or higher

• Claude Desktop or other MCP-compatible client

Quick Install

# Clone or navigate to the project directory
cd cms-datagov-mcp-server

# Install dependencies
npm install

# Build the TypeScript code
npm run build

# Link globally (for Claude Desktop)
npm link

Configure Claude Desktop

Edit your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

Linux: ~/.config/Claude/claude_desktop_config.json

Add this configuration:

{
  "mcpServers": {
    "cms-datagov": {
      "command": "cms-datagov-mcp-server",
      "args": [],
      "env": {}
    }
  }
}

Restart Claude Desktop to activate the server.

Usage

Search for Datasets

"Search CMS datasets for TEAM episode"

Returns a list of matching datasets with IDs, descriptions, and available formats.

Get Dataset Details

"Get details for dataset 9887a515-7552-4693-bf58-735c77af46d7"

Returns comprehensive metadata including API endpoints, CSV links, and column information.

Query Dataset Records

"Query dataset 9887a515-7552-4693-bf58-735c77af46d7 where organization_ccn=100007, return 100 rows"

Returns up to 5000 rows with optional filtering, sorting, and column selection.

Get Dataset Statistics

"Get statistics for dataset 9887a515-7552-4693-bf58-735c77af46d7"

Returns column names, types, and metadata about the dataset.

Get CSV Download Link

"Get CSV link for dataset 9887a515-7552-4693-bf58-735c77af46d7"

Returns direct download URL for creating Athena EXTERNAL TABLEs.

API Reference

cms_search_datasets

Search CMS datasets by keyword, theme, or title.

Parameters:

• query (optional): Search term for titles, descriptions, or keywords

• theme (optional): Filter by theme (e.g., 'Medicare', 'Medicaid')

• limit (optional): Maximum results to return (default: 10)

Returns: Array of matching datasets with metadata

cms_get_dataset

Get detailed information about a specific dataset.

Parameters:

• dataset_id (required): UUID of the dataset

Returns: Complete dataset metadata including API endpoint and CSV URL

cms_query_dataset

Query dataset records with filtering and pagination.

Parameters:

• dataset_id (required): UUID of the dataset

• filter (optional): Filter expression (e.g., [field]=value)

• columns (optional): Comma-separated column list

• sort (optional): Column to sort by (prefix with - for descending)

• offset (optional): Number of rows to skip (default: 0)

• size (optional): Number of rows to return (max 5000, default: 100)

Returns: JSON array of matching records

cms_get_dataset_stats

Get statistics about a dataset.

Parameters:

• dataset_id (required): UUID of the dataset

Returns: Column information and dataset metadata

cms_get_csv_link

Get direct CSV download URL.

Parameters:

• dataset_id (required): UUID of the dataset

Returns: CSV download URL with usage instructions

Integration with Athena

For large datasets or complex analysis:

1. Use cms_get_csv_link to get the download URL

2. Download CSV to your S3 bucket

3. Create an Athena EXTERNAL TABLE:

CREATE EXTERNAL TABLE cms_team_data (
  organization_ccn STRING,
  organization_name STRING,
  -- ... other columns
)
ROW FORMAT DELIMITED
FIELDS TERMINATED BY ','
STORED AS TEXTFILE
LOCATION 's3://your-bucket/cms-data/'
TBLPROPERTIES ('skip.header.line.count'='1');

4. Run complex SQL queries in Athena

Troubleshooting

Server Not Appearing in Claude Desktop

1. Verify the server is linked: npm list -g @clarify/cms-datagov-mcp-server

2. Check configuration file syntax (valid JSON)

3. Restart Claude Desktop completely

4. Check Claude Desktop logs for errors

API Errors

• 404 Not Found: Invalid dataset ID

• Timeout: Dataset too large, use CSV download instead

• Rate Limit: Wait a moment and retry

Build Errors

# Clean and rebuild
rm -rf build node_modules
npm install
npm run build

CMS API Details

• Base URL: https://data.cms.gov/data-api/v1

• Catalog: https://data.cms.gov/data.json

• Max Rows: 5000 per request

• No Authentication: Public data, no API key required

When to Use MCP vs Athena

Use MCP for:

• Dataset discovery and exploration

• Quick lookups (< 1000 rows)

• Data validation

• Getting CSV links

Use Athena for:

• Large datasets (> 5000 rows)

• Complex joins and aggregations

• GROUP BY operations

• Repeated analysis

Development

Build

npm run build

Watch Mode

npm run watch

Testing

node test-validation.mjs

License

MIT License - See LICENSE file for details

Support

For CMS API questions: OEDAUserResearch@cms.hhs.gov

For MCP protocol documentation: https://modelcontextprotocol.io/

Related Resources

• CMS API Documentation

• CMS API Guide PDF

• Model Context Protocol

• Claude Desktop