cdc-health-mcp-server
Public Hosted Server: https://cdc.caseyjhand.com/mcp
Overview
CDC public health data from the CDC Open Data portal and CDC WONDER. Search 1,000+ datasets on vaccination, surveillance, and behavioral risk, inspect their schemas and query them with SoQL, or pull national mortality statistics by year, month, age, sex, race, Hispanic origin, or cause of death.
Tools
Tool | Description |
| Search the CDC dataset catalog by keyword, category, tag, or asset type |
| Fetch column schema, row count, and metadata for a dataset |
| List the catalog's category and tag values with their entry counts |
| Execute SoQL queries — filter, aggregate, sort, full-text search, select fields |
| Query CDC WONDER for national mortality, population, and death rates across five databases |
| List the WONDER tables staged for SQL, with their row counts, columns, and expiry |
| Run one read-only SQL SELECT over the staged WONDER tables |
The two dataframe tools are listed only where the deployment sets CANVAS_PROVIDER_TYPE=duckdb.
Resources
Resource | Description |
| Top 50 most-viewed catalog entries, for orientation |
| Dataset metadata and the first 100 columns for a specific dataset |
Both resources mirror data also reachable via cdc_discover_datasets and cdc_get_dataset_schema, for clients that surface resources but not tools.
Prompts
Prompt | Description |
| Guided workflow for investigating a public health question across CDC data |
Skill
Skill | Description |
| Gates for agents comparing or trending results: which WONDER rate to compare across groups, race beside Hispanic origin, the provisional database's partial year and withheld causes, finding a peak month, splicing WONDER databases, ranking or comparing a staged WONDER table, reading stratified Socrata tables, and reaching a file entry |
Ships in skills/ for plugin installs, the npm package, the Docker image, and the .mcpb bundle, and is served over MCP as skill://cdc-health-guide/SKILL.md.
Related MCP server: mcp-data-orlando
Capability reference
cdc_discover_datasets tool
Filters:
query,category,tags, andasset_types(dataset,filter,chart,map,story,file,href;["dataset", "filter"]keeps the entries with rows to query).tagsunion — a dataset matches when it carries any one of them, so each tag added widens the result set — whilequery,category, andasset_typesintersect with them.limitdefaults to 10;offset + limitis capped at 10,000 (page_out_of_rangepast it).orderdefaults torelevancewhenqueryis set anddataset_idotherwise; relevance order varies between calls, so onlydataset_idpages every match exactly onceResults carry
assetType,permalink,columnCount(0 marks a chart, map, or other non-tabular asset), an 8-namecolumnSample, and a description cut to 300 characters, plustotalCountandappliedFilters. A link (href) entry's destinations are inaccessPoints, and the datasets a chart, map, filter, or story is built on inparentIds. A file entry carriesdownloadUrl(https://<domain>/download/<id>, which redirects to the file) and, where the catalog records one,mimeTypeWhen a
categoryortagsvalue matches nothing, thenoticenames the closest catalog values with their entry counts, e.g.Vaccination→"Vaccinations" (89 entries)
cdc_get_dataset_schema tool
Takes a four-by-four
datasetId(e.g.bi63-dtpu; an uppercase ID is lowercased first).column_limit(default 100) andcolumn_offsetpage wide schemas, reportingtotalCount,truncated, andnextOffsetThe dataset
descriptionis capped at 4,000 characters by default (descriptionTruncatedanddescriptionLengthare set when cut);full_description: truereturns the whole textColumns carry
fieldName,dataType, anddescription.rowCountSourcesays whetherrowCountisliveor Socrata'scachedfigureWhere the publisher recorded them,
temporalCoverage,updateFrequency,geographicCoverage,citation,license, andattributioncome back as the publisher's own text, and a filter carriesparentId, the dataset it is a view ofA chart or map fails with
not_queryable, naming the dataset it is built on; a file fails the same way, naming its file name and size where CDC records them and thedownloadUrlto fetch it from
cdc_list_catalog_vocabulary tool
Every category comes back whole; the ~1,600 tags are ranked by entry count and paged with
tag_limit(default 50) andtag_offset.filter(up to 500 characters) narrows both by word match, not fuzzy matching; a word under 3 letters or digits matches whole words onlyEach value carries
datasetCount; the response also reportsvocabularySize,categoryCount,tagCount,truncated,nextOffset, andtruncationCeiling(an upper bound on the counts of the tags after the page)
cdc_query_dataset tool
Clauses:
select,where,group,having,order, and full-textsearch. Up to 1,000 rows per call (default 100; a largerlimitis clamped, and the notice names the clamp when rows remain),offsetup to 1,000,000For stable offset paging, set an
orderending in a unique tie-breaker (:idon ungrouped rows, the grouped columns on a grouped query); the notice says so when it is missingeffectiveQueryechoes the SoQL clauses as sent;truncatedandnextOffsetreport paging, with nototalCount. A chart or map ID fails withnot_queryable, naming the dataset it is built on
cdc_query_wonder tool
| CDC database | Years | Race groups |
|
| D76 — Underlying Cause of Death | 1999–2020 | 4 bridged | — |
| D176 — Provisional Mortality Statistics | 2018 → current year (latest year partial) | 6 single-race | yes |
| D158 — Underlying Cause of Death, Single Race | 2018–2024 | 6 single-race | — |
| D77 — Multiple Cause of Death | 1999–2020 | 4 bridged | yes |
| D157 — Multiple Cause of Death, Single Race | 2018–2024 | 6 single-race | yes |
group_bytakes 1–4 ofyear,month,age_group,sex,race,hispanic_origin,icd_chapter,icd_subchapter,cause_113,leading_causes(alone only), andinjury_intent; results are always national. A grouping that could produce more than 10,000 rows is refused before any request.cause_icd10andmcd_icd10take an ICD-10 code, a range (X40-X49), or a list of up to 50.age_groupstakesNS(age not stated) alone or with all eleven known groups.racereports four bridged groups on the 1999–2020 databases and six single-race groups on the rest; the two families' series are not comparablecause_icd10andmcd_icd10codes are uppercased before they are checked, sox40-x49reads asX40-X49limitpages the table fetched from CDC; omitted, it returns the rest of the table fromoffset, up to 10,000 rows per call, or 100 rows where tables are staged (below). A largerlimitis lowered to that ceiling, which equals the table-size bound, so one call always holds the whole table.offsetgoes up to 10,000Where the deployment has a DataCanvas (
CANVAS_PROVIDER_TYPE=duckdb), a call atoffset0 that leaves rows past its page stages the whole table aswonder_<10 characters>and names it instagedTable. The staged table holds the inline columns in CDC's row order, then a<measure>_statuscolumn per measure carrying CDC's token (Suppressed,Unreliable,Not Applicable) where the value is null. It is dropped an hour after the last query that read it, or earlier, earliest-expiring first, once 200 are staged.cdc_dataframe_queryreads it with SQL and no further WONDER request; a lateroffsetstages nothing. A failure to stage fails the call asstaging_failedRows carry
deaths,population,crude_rate, andage_adjusted_ratewhere age can be standardized, each rate followed by its 95% confidence interval (crude_rate_lowerandcrude_rate_upper,age_adjusted_rate_lowerandage_adjusted_rate_upper),nullwhere CDC sent none. Chapter and sub-chapter rows addcause_code, the ICD-10 rangecause_icd10takes;cause_113rows addcause_level;monthrows carry deaths only. Cells CDC returns asSuppressed,Unreliable, orNot Applicablereadnulland are listed incellNotes;messagescarries every message CDC attached, among them the ones saying it hid rows, andtotalCountis exactThe
provisionaldatabase's latest year covers part of the year against a full-year population, and CDC withholds some recent causes; anoticesays so whenever a query reaches either, and on amonthgrouping names the month the data ends in as partialCDC rejects requests less than 15 seconds apart, so calls are queued one at a time and spaced 16 seconds apart. A request WONDER has not finished answering within 20 seconds fails as a retryable
upstream_error
cdc_dataframe_describe tool
Lists the staged tables as
tables, each withname,rowCount,expiresAt, andcolumns(name,type):VARCHARfor dimensions,cause_code, and the_statuscolumns,INTEGERforcause_level,DOUBLEfor deaths, population, rates, and interval boundstablenarrows it to one; a table that is not staged failsmissing_table. With nothing staged it returns an empty list and a notice saying how to stage oneThe list can include tables other sessions on the server staged
cdc_dataframe_query tool
Runs one read-only DuckDB
SELECTover the staged tables:SELECT * FROM <name> LIMIT <n> OFFSET <m>continues acdc_query_wonderpage where it stopped, and any other SELECT ranks, compares, or aggregates the whole table. Other statements are refused asinvalid_sql, and file and network functions asdenied_function. A column named__proto__failsreserved_column_name; rename it withASlimitdefaults to 100 and is lowered to 1,000 with a notice;truncated,shown,cap, and anoticereport rows past it. Rows totalling more than 1,000,000 bytes as JSON at thatlimit, measured before any row is returned, failresult_too_largeA table that is not staged fails
missing_table;cdc_dataframe_describelists what is. Counts and otherBIGINTresults come back as strings
cdc://datasets resource
Top 50 catalog entries by popularity, each with
id,name,assetType,category,columnCount, andupdatedAt, plus the catalogtotalCountcolumnCount: 0marks a non-tabular entry;cdc_discover_datasetssearches and pages the full catalog
cdc://datasets/{datasetId} resource
Dataset metadata plus the first 100 columns as
application/json, withcolumnCountandtruncated; the description is capped at 4,000 characters. It carries the sameparentIdand publisher fields ascdc_get_dataset_schema, and a chart or map fails withnot_queryable, naming its parent dataset, a file the same way with its download URL. An uppercasedatasetIdis lowercased firstFor more columns or the full description, use
cdc_get_dataset_schemawithcolumn_offsetorfull_description: true
analyze_health_trend prompt
Arguments:
topicrequired;timeRangeandgeographyoptionalReturns one user message that routes the question to
cdc_query_wonder(national mortality) or the Socrata tools (everything else), then walks discover → inspect → baseline → compare → synthesize
Features
Built on @cyanheads/mcp-ts-core: stdio and Streamable HTTP transports, pluggable auth (none / jwt / oauth), swappable storage (in-memory, filesystem, Supabase, Cloudflare KV/R2/D1), structured logging with optional OpenTelemetry tracing.
CDC-specific:
The Socrata SODA API v2.1 over the CDC Open Data portal (~1,080 datasets); no auth required, and an optional app token raises rate limits
CDC WONDER mortality data from five databases covering 1999 through the current year, reached over its XML request API
The four Socrata tools take a
domaininput, limited todata.cdc.gov(default) andchronicdata.cdc.gov; both serve the same catalogcategoryandtagsmust match the catalog's own values (matched ignoring case, otherwise exactly);cdc_list_catalog_vocabularylists themSocrata returns values as strings (geo columns as GeoJSON objects), and a column like
yearis numeric in some datasets and text in others. Match WHERE literals to the column'sdataType: numbers bare, strings single-quoted
Agent-friendly output:
Paging is reported explicitly:
totalCount,truncated,nextOffset, andshown/cap.limitsets the page:cdc_query_datasetclamps it to 1,000 rows, naming the clamp in thenoticewhen rows remain, andcdc_query_wonderlowers it to 10,000, its table-size bound (an omittedlimitis 100 rows where the whole table is staged for SQL); up to those ceilings a page ends short oflimitonly at the end of the result setTyped errors with a recovery hint on every declared reason, such as
not_queryable,page_out_of_range, andinvalid_queryUpstream gaps stay visible: WONDER status tokens in
cellNotes, hidden-row notices inmessages, androwCountSourceon schema row countseffectiveQueryechoes the SoQL clauses or a WONDER query summary, so a result can be reproduced
Getting started
Connect to the hosted instance, no install:
claude mcp add --transport http cdc-health-mcp-server https://cdc.caseyjhand.com/mcpOr run it locally:
claude mcp add cdc-health-mcp-server -- npx -y @cyanheads/cdc-health-mcp-serverFor other clients, add this to the MCP config file:
{
"mcpServers": {
"cdc-health-mcp-server": {
"command": "npx",
"args": ["-y", "@cyanheads/cdc-health-mcp-server"]
}
}
}Setting CDC_APP_TOKEN to a Socrata app token raises the Socrata rate limits. For Docker or a source build, see Running the server.
Configuration
Variable | Description | Default |
| Socrata app token; raises rate limits. | none |
| SODA host for requests with no |
|
| Socrata Discovery API base URL. |
|
| Fold the letter case of ICD-10 codes (to upper) and dataset IDs (to lower) before their pattern check. |
|
|
|
|
| Transport: |
|
| HTTP server port. |
|
| HTTP session mode: |
|
| Authentication: |
|
| Log level ( |
|
| Enable OpenTelemetry. |
|
See .env.example for the full list of optional overrides.
Running the server
Local development
Requires Bun v1.4.4 or higher (or Node.js v24+).
Clone and install:
git clone https://github.com/cyanheads/cdc-health-mcp-server.git cd cdc-health-mcp-server && bun install cp .env.example .env # optionally set CDC_APP_TOKENBuild and run the production version:
# One-time build bun run rebuild # Run the built server bun run start:http # or bun run start:stdioRun checks and tests:
bun run devcheck # Lints, formats, type-checks, and more bun run test # Runs the test suite
Docker
docker run --rm -p 3010:3010 ghcr.io/cyanheads/cdc-health-mcp-server:latestThe image defaults to HTTP transport, stateless session mode, and logs to /var/log/cdc-health-mcp-server. To run it over stdio from an MCP client, use "command": "docker" with "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/cdc-health-mcp-server:latest"]. To build locally, docker build -t cdc-health-mcp-server .; OpenTelemetry peer dependencies are installed by default — build with --build-arg OTEL_ENABLED=false to omit them.
Project structure
Directory | Purpose |
|
|
| Server-specific environment variable parsing and validation with Zod. |
| Tool definitions ( |
| Resource definitions. Catalog overview and dataset detail. |
| Prompt definitions. Health trend analysis workflow. |
| Socrata service — catalog search, vocabularies, metadata, SoQL queries. |
| CDC WONDER service — XML request builder, response parser, request spacing, the staged-table projection. |
| Hands the framework's DataCanvas to handlers; unset where the deployment has none. |
| Shared input schemas — case-normalized ICD-10 codes and dataset IDs. |
| Shared helpers — HTML-to-text, table-cell escaping, vocabulary matching. |
| Agent skill published to agents that install the server, and served over MCP as |
| Unit and integration tests mirroring |
Development guide
See CLAUDE.md for development guidelines and architectural rules. The short version:
Handlers throw, framework catches — no
try/catchin tool logicUse
ctx.logfor logging,ctx.statefor storageRegister new tools and resources in the
createApp()arrays insrc/index.tsWrap external API calls: validate raw → normalize to domain type → return output schema; never fabricate missing fields
Contributing
Issues are welcome. Run checks and tests before submitting:
bun run devcheck
bun run testLicense
Apache-2.0 — see LICENSE for details.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Unofficial CDC MCP — wraps CDC open data via Socrata API (data.cdc.gov)
Search and query government open-data portals (Socrata SODA API).
Query and explore Nova Scotia open datasets via the Socrata SODA API.
Query, filter, aggregate, and link Georgia education, Census, immigration, and health datasets.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceProvides access to 73 CDC public health datasets covering disease surveillance, vaccination tracking, behavioral risk factors, environmental health, and outbreak detection across 18 surveillance systems through the Socrata Open Data API.2MIT
- AlicenseNot gradedqualityBmaintenanceEnables searching and querying Orlando Open Data datasets via Socrata SoQL, providing access to metadata and data rows through natural language or direct tool calls.154 npmMIT
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to query U.S. public-health datasets such as disease surveillance, mortality, behavioral risk factors, and flu activity through the Socrata API, using natural language or direct tool calls.98 npmMIT
- AlicenseAqualityCmaintenanceEnables AI clients to search and read over 2,400 New York City public datasets through the Socrata SODA API, with ready-made tools for restaurant health inspections and 311 service requests plus general dataset discovery and querying.4MIT