Cdc Health MCP Server README

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

Resources

Both resources mirror data also reachable via cdc_discover_datasets and cdc_get_dataset_schema, for clients that surface resources but not tools.

Prompts

Skill

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.

Capability reference

cdc_discover_datasets _tool

• Filters: query, category, tags, and asset_types (dataset, filter, chart, map, story, file, href; ["dataset", "filter"] keeps the entries with rows to query). tags union — a dataset matches when it carries any one of them, so each tag added widens the result set — while query, category, and asset_types intersect with them. limit defaults to 10; offset + limit is capped at 10,000 (page_out_of_range past it). order defaults to relevance when query is set and dataset_id otherwise; relevance order varies between calls, so only dataset_id pages every match exactly once
• Results carry assetType, permalink, columnCount (0 marks a chart, map, or other non-tabular asset), an 8-name columnSample, and a description cut to 300 characters, plus totalCount and appliedFilters. A link (href) entry's destinations are in accessPoints, and the datasets a chart, map, filter, or story is built on in parentIds
• When a category or tags value matches nothing, the notice names the closest catalog values with their entry counts, e.g. Vaccination → "Vaccinations" (89 datasets)

cdc_get_dataset_schema _tool

• Takes a four-by-four datasetId (e.g. bi63-dtpu). column_limit (default 100) and column_offset page wide schemas, reporting totalCount, truncated, and nextOffset
• The dataset description is capped at 4,000 characters by default (descriptionTruncated and descriptionLength are set when cut); full_description: true returns the whole text
• Columns carry fieldName, dataType, and description. rowCountSource says whether rowCount is live or Socrata's cached figure
• Where the publisher recorded them, temporalCoverage, updateFrequency, geographicCoverage, citation, license, and attribution come back as the publisher's own text, and a filter carries parentId, the dataset it is a view of
• A chart or map fails with not_queryable, naming the dataset it is built on

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) and tag_offset. filter (up to 500 characters) narrows both by word match, not fuzzy matching; a word under 3 letters or digits matches whole words only
• Each value carries datasetCount; the response also reports vocabularySize, categoryCount, tagCount, truncated, nextOffset, and truncationCeiling (an upper bound on the counts of the tags after the page)

cdc_query_dataset _tool

• Clauses: select, where, group, having, order, and full-text search. Up to 1,000 rows per call (default 100; a larger limit is clamped, and the notice names the clamp when rows remain), offset up to 1,000,000
• For stable offset paging, set an order ending in a unique tie-breaker (:id on ungrouped rows, the grouped columns on a grouped query); the notice says so when it is missing
• effectiveQuery echoes the SoQL clauses as sent; truncated and nextOffset report paging, with no totalCount. A chart or map ID fails with not_queryable, naming the dataset it is built on

cdc_query_wonder _tool

• group_by takes 1–4 of year, month, age_group, sex, race, hispanic_origin, icd_chapter, icd_subchapter, cause_113, leading_causes (alone only), and injury_intent; results are always national. A grouping that could produce more than 10,000 rows is refused before any request. cause_icd10 and mcd_icd10 take an ICD-10 code, a range (X40-X49), or a list of up to 50. age_groups takes NS (age not stated) alone or with all eleven known groups. race reports four bridged groups on the 1999–2020 databases and six single-race groups on the rest; the two families' series are not comparable
• limit pages the table fetched from CDC; omitted, it returns the rest of the table from offset, up to 10,000 rows per call. A larger limit is lowered to that ceiling, which equals the table-size bound, so one call always holds the whole table. offset goes up to 10,000
• Rows carry deaths, population, crude_rate, and age_adjusted_rate where age can be standardized, each rate followed by its 95% confidence interval (crude_rate_lower and crude_rate_upper, age_adjusted_rate_lower and age_adjusted_rate_upper), null where CDC sent none. Chapter and sub-chapter rows add cause_code, the ICD-10 range cause_icd10 takes; cause_113 rows add cause_level; month rows carry deaths only. Cells CDC returns as Suppressed, Unreliable, or Not Applicable read null and are listed in cellNotes; messages reports rows CDC hid, and totalCount is exact
• The provisional database's latest year covers part of the year against a full-year population, and CDC withholds some recent causes; a notice says so whenever a query reaches either, and on a month grouping names the month the data ends in as partial
• CDC 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://datasets _resource

• Top 50 catalog entries by popularity, each with id, name, assetType, category, columnCount, and updatedAt, plus the catalog totalCount
• columnCount: 0 marks a non-tabular entry; cdc_discover_datasets searches and pages the full catalog

cdc://datasets/{datasetId} _resource

• Dataset metadata plus the first 100 columns as application/json, with columnCount and truncated; the description is capped at 4,000 characters. It carries the same parentId and publisher fields as cdc_get_dataset_schema, and a chart or map fails with not_queryable, naming its parent dataset
• For more columns or the full description, use cdc_get_dataset_schema with column_offset or full_description: true

analyze_health_trend _prompt

• Arguments: topic required; timeRange and geography optional
• Returns 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 domain input, limited to data.cdc.gov (default) and chronicdata.cdc.gov; both serve the same catalog
• category and tags must match the catalog's own values (matched ignoring case, otherwise exactly); cdc_list_catalog_vocabulary lists them
• Socrata returns values as strings (geo columns as GeoJSON objects), and a column like year is numeric in some datasets and text in others. Match WHERE literals to the column's dataType: numbers bare, strings single-quoted

Agent-friendly output:

• Paging is reported explicitly: totalCount, truncated, nextOffset, and shown/cap. limit sets the page: cdc_query_dataset clamps it to 1,000 rows, naming the clamp in the notice when rows remain, and cdc_query_wonder lowers it to 10,000, its table-size bound; up to those ceilings a page ends short of limit only at the end of the result set
• Typed errors with a recovery hint on every declared reason, such as not_queryable, page_out_of_range, and invalid_query
• Upstream gaps stay visible: WONDER status tokens in cellNotes, hidden-row notices in messages, and rowCountSource on schema row counts
• effectiveQuery echoes 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/mcp

Or run it locally:

claude mcp add cdc-health-mcp-server -- npx -y @cyanheads/cdc-health-mcp-server

For 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

See .env.example for the full list of optional overrides.

Running the server

Local development

Requires Bun v1.4.0 or higher (or Node.js v24+).

• Clone and install:

  shCopy

  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_TOKEN
  

• Build and run the production version:

  shCopy

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:http
  # or
  bun run start:stdio
  

• Run checks and tests:

  shCopy

  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:latest

The 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

Development guide

See CLAUDE.md for development guidelines and architectural rules. The short version:

• Handlers throw, framework catches — no try/catch in tool logic
• Use ctx.log for logging, ctx.state for storage
• Register new tools and resources in the createApp() arrays in src/index.ts
• Wrap 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 test

License

Apache-2.0 — see LICENSE for details.