Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@cms-datagov-mcp-server Query dataset 9887a515-7552-4693-bf58-735c77af46d7 for organization CCN 100007"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
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
cms_search_datasets - Find datasets by keyword or theme
cms_get_dataset - Get detailed dataset information
cms_query_dataset - Query data with filters (up to 5000 rows)
cms_get_dataset_stats - Get row counts and column info
cms_get_csv_link - Get CSV download URL for Athena
cms://datasets - Browse all available CMS datasets
cms://dataset/{id} - Access specific dataset metadata
cms://csv/{id} - Get CSV download link
Node.js 18 or higher
Claude Desktop or other MCP-compatible client
# 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 linkEdit 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.
"Search CMS datasets for TEAM episode"Returns a list of matching datasets with IDs, descriptions, and available formats.
"Get details for dataset 9887a515-7552-4693-bf58-735c77af46d7"Returns comprehensive metadata including API endpoints, CSV links, and column information.
"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 statistics for dataset 9887a515-7552-4693-bf58-735c77af46d7"Returns column names, types, and metadata about the dataset.
"Get CSV link for dataset 9887a515-7552-4693-bf58-735c77af46d7"Returns direct download URL for creating Athena EXTERNAL TABLEs.
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
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
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
Get statistics about a dataset.
Parameters:
dataset_id (required): UUID of the dataset
Returns: Column information and dataset metadata
Get direct CSV download URL.
Parameters:
dataset_id (required): UUID of the dataset
Returns: CSV download URL with usage instructions
For large datasets or complex analysis:
Use cms_get_csv_link to get the download URL
Download CSV to your S3 bucket
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');Run complex SQL queries in Athena
Verify the server is linked: npm list -g @clarify/cms-datagov-mcp-server
Check configuration file syntax (valid JSON)
Restart Claude Desktop completely
Check Claude Desktop logs for errors
404 Not Found: Invalid dataset ID
Timeout: Dataset too large, use CSV download instead
Rate Limit: Wait a moment and retry
# Clean and rebuild
rm -rf build node_modules
npm install
npm run buildBase 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
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
npm run buildnpm run watchnode test-validation.mjsMIT License - See LICENSE file for details
For CMS API questions: OEDAUserResearch@cms.hhs.gov
For MCP protocol documentation: https://modelcontextprotocol.io/
Get the direct CSV download URL for a dataset. Use this to download large datasets and create Athena EXTERNAL TABLEs for complex analysis.
| Name | Required | Description | Default |
|---|---|---|---|
| dataset_id | Yes | The unique identifier (UUID) of the dataset |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It implies a read-only URL fetch, but does not disclose URL expiry, required dataset state, permission requirements, or whether the link is stable across calls. The Athena EXTERNAL TABLE hint is useful but is usage guidance, not behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core action, and the second sentence immediately justifies when to reach for it. No filler or repetition of the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter read tool with no output schema, the description conveys what comes back (a direct CSV download URL) and its intended downstream use. Only minor gaps remain, such as URL lifetime or whether the dataset must be finalized before a link is available.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for the single required dataset_id (UUID), so the schema already documents the parameter fully. The description adds no format, sourcing, or retrieval guidance beyond that. Baseline 3 applies when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb+resource: retrieves the direct CSV download URL for a dataset. Clearly distinct in intent from cms_query_dataset (which presumably returns data rows) and cms_get_dataset_stats, but the description does not name or contrast with those siblings explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides a clear use context: 'Use this to download large datasets and create Athena EXTERNAL TABLEs for complex analysis.' That tells the agent when this tool is appropriate. It stops short of naming the alternative tools or stating when NOT to use it (e.g. small result sets, ad-hoc queries).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get detailed information about a specific CMS dataset by its ID. Returns metadata, API endpoints, CSV download URLs, and usage information.
| Name | Required | Description | Default |
|---|---|---|---|
| dataset_id | Yes | The unique identifier (UUID) of the dataset |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. 'Get' implies a read-only lookup and the description helpfully enumerates the return payload (metadata, endpoints, CSV URLs, usage info), but it says nothing about auth requirements, rate limits, or error behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two compact sentences, with the core action front-loaded before the return-value enumeration. The return list is slightly long but each item is informative rather than filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-parameter read tool with no output schema, the description compensates well by summarizing what is returned. It is near-complete; only the sibling routing and prerequisite information are missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the single parameter is fully documented (UUID format) in the schema. The description's 'by its ID' only echoes that, adding no syntax or format detail beyond the schema baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ('Get detailed information about a specific CMS dataset') and the lookup key ('by its ID'). It does not distinguish itself from siblings like cms_get_csv_link, which its return-value list (CSV download URLs) partially overlaps with.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The only usage signal is the implicit 'by its ID', meaning the agent must already possess the identifier. There is no statement of when to use this versus cms_search_datasets or cms_get_dataset_stats, and no prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get statistics about a CMS dataset including total row count and column information. Useful for understanding dataset size before querying.
| Name | Required | Description | Default |
|---|---|---|---|
| dataset_id | Yes | The unique identifier (UUID) of the dataset |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It does disclose the return payload (row count, column info), which is valuable given there is no output schema, but it never states that this is a safe read-only operation, nor anything about auth or cost. Adequate but incomplete for a zero-annotation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, zero padding, and the primary capability is front-loaded before the usage hint. Nothing here could be cut without losing information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter read tool with no output schema, the description covers both what is returned and when to reach for it. The only shortfall is the vagueness of 'column information' as a return description, but overall the agent has enough to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There is a single parameter with 100% schema description coverage ('The unique identifier (UUID) of the dataset'), so the schema already fully documents it. The description adds no format or semantics beyond that, which is the expected baseline when the schema does the work.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description gives a specific verb+resource ('Get statistics about a CMS dataset') and enumerates the payload ('total row count and column information'), which distinguishes it from siblings like cms_query_dataset. It does not, however, explicitly contrast itself with cms_get_dataset or cms_search_datasets, so an agent must infer the boundary.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Useful for understanding dataset size before querying' supplies a concrete usage context and implicitly sequences the call ahead of cms_query_dataset. There is no explicit when-not guidance or named alternative, but the triggering condition is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Query a CMS dataset with filters, sorting, and pagination. Returns up to 5000 rows per request. For larger datasets, use csv_link and load into Athena.
| Name | Required | Description | Default |
|---|---|---|---|
| size | No | Number of rows to return (max 5000, default 100) | |
| sort | No | Column name to sort by (prefix with - for descending) | |
| filter | No | Filter expression (e.g., '[field]=value' or '[field]=value1,value2') | |
| offset | No | Number of rows to skip (for pagination) | |
| columns | No | Comma-separated list of columns to return | |
| dataset_id | Yes | The unique identifier (UUID) of the dataset |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full behavioral burden. It discloses the row limit (5000) and mentions pagination parameters, which is helpful, but omits important traits such as authentication requirements, rate limits, or what happens when filters are invalid. The mention of 'Returns up to 5000 rows' is a useful constraint but insufficient for a query tool with no annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core functionality and a key operational limit. Every sentence earns its place by quickly establishing scope and a fallback for larger datasets.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of a query tool with six parameters and no output schema, the description covers the essential constraints (row limit, pagination alternative). It is nearly complete, though it could benefit from a brief note on return format or error handling to fully guide the agent in edge cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, meaning all parameters are fully documented in the schema itself. The description does not add any parameter-specific details beyond what is already present, such as filter syntax or sort direction format. Baseline score of 3 is appropriate when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Query a CMS dataset') and names the supported operations (filters, sorting, pagination). However, it doesn't differentiate from siblings like cms_search_datasets or cms_get_dataset, leaving the agent to infer that this tool retrieves actual row data rather than metadata.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: it returns up to 5000 rows and suggests using csv_link for larger datasets, which is a useful when-to-use-exclusion. It lacks explicit guidance on when to choose this tool over cms_search_datasets or cms_get_dataset_stats, which would resolve ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search CMS datasets by keyword, theme, or title. Returns a list of matching datasets with their IDs, titles, descriptions, and available formats.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of results to return (default: 10) | |
| query | No | Search term to find in dataset titles, descriptions, or keywords | |
| theme | No | Filter by theme (e.g., 'Medicare', 'Medicaid', 'Hospital') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It helpfully discloses the return shape (IDs, titles, descriptions, formats), but says nothing about pagination, result limits beyond the default, rate limits, or that this is a safe read-only operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences: the first states purpose, the second states the return contents. Nothing is wasted and the most important information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple search tool with full schema coverage and no output schema, the description covers purpose and return structure adequately. It misses routing guidance versus alternative query/get tools and result-pagination behavior, but those are minor for this complexity level.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds only a light echo of the query/theme parameters ('keyword, theme, or title') and no additional syntax, format, or matching behavior details beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb (Search) and resource (CMS datasets) with the searchable facets (keyword, theme, title). It clearly conveys what the tool does, though it does not explicitly differentiate itself from siblings like cms_query_dataset or cms_get_dataset.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives no explicit when-to-use guidance, no exclusions, and never names an alternative among the several sibling tools. Usage is only implied by the search-oriented phrasing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.4cms_get_csv_linkcms_get_datasetcms_get_dataset_statscms_query_datasetcms_search_datasetsScored across 5 tools
Each tool targets a distinct operation: querying, stats, CSV link, search, and metadata retrieval. cms_get_dataset and cms_get_dataset_stats could be slightly confused, but descriptions clarify their purposes.
All tool names follow a consistent snake_case pattern with the 'cms_' prefix and clear verb_noun structure, making them predictable and easy to scan.
Five tools are well-scoped for a data catalog server, covering discovery, metadata, querying, stats, and export without redundancy.
The tool set covers key aspects of dataset interaction, but lacks tools for schema exploration (e.g., listing columns) or direct data export beyond CSV links, which might be needed for some workflows.
US healthcare data for AI agents: CMS, FDA adverse events, CDC, NPPES NPI. Keyless, real samples.
CMS Open Payments, with annual dataset discovery through the official DKAN API.
CMS quality ratings, payer-negotiated prices, and clinician data for 41K+ US healthcare facilities.
Live US drug acquisition costs (CMS NADAC) for AI assistants. Free, no auth, weekly data.
