Tools

Four tools for discovering and querying CDC public health data. Three query the CDC Open Data portal (Socrata); one queries CDC WONDER mortality statistics:

cdc_discover_datasets

Search the CDC dataset catalog to find relevant datasets.

• Full-text search across dataset names and descriptions
• Filter by domain category (e.g., "NNDSS", "Vaccinations", "Behavioral Risk Factors")
• Filter by domain tags (e.g., ["covid19", "surveillance"]) — a dataset matches on any one tag, so each tag added widens the result set; narrow with query or category, which intersect with the tag set
• Returns dataset IDs, names, truncated descriptions, a column count with a short column sample, and update timestamps — use cdc_get_dataset_schema for the full column list
• Each result carries its catalog assetType (dataset, filter, chart, map, story, file, href); a columnCount of 0 marks an entry that is not tabular and yields no data from the other tools
• Pagination via offset for browsing large result sets — offset plus limit must not exceed 10,000, the ceiling the catalog enforces
• domain selects the host contacted, data.cdc.gov (default) or chronicdata.cdc.gov — both front the same catalog and return the same entries, so switching hosts neither widens nor narrows a search

cdc_get_dataset_schema

Fetch the column schema for a specific dataset.

• Column names, data types, and full descriptions — never truncated per column
• Row count and last-updated timestamp
• Essential for understanding column types before writing $where clauses
• Accepts four-by-four dataset identifiers (e.g., bi63-dtpu)
• Returns the first 100 columns by default. Catalog schemas run from 3 to 322 columns, so every ordinary dataset arrives whole; wider ones report totalCount, truncated, and a nextOffset to pass back as column_offset. Raise column_limit (max 500) to pull a wide schema in one call
• A column_offset at or past the column count returns an empty window rather than an error
• Fails with not_queryable when the ID names a non-tabular catalog asset, rather than returning an empty column list
• domain selects the host contacted, data.cdc.gov (default) or chronicdata.cdc.gov — a four-by-four ID resolves on either

cdc_query_dataset

Execute SoQL queries against any CDC dataset.

• Full SoQL support: $select, $where, $group, $having, $order
• Full-text search across all text columns via $q
• Up to 5,000 rows per request with pagination
• truncated is measured, not guessed: the request fetches one row past the limit and drops it, so a page that fills the limit exactly is reported as complete instead of sending you paginating an aggregate
• nextOffset names where to resume whenever rows remain. Pair it with an order clause — SODA does not order results implicitly, and order=":id" works on any dataset
• Rows are also bounded by a 200,000-character response budget, so a wide dataset at limit: 5000 returns a usable page with a nextOffset rather than several megabytes
• Returns the SoQL clauses it sent as effectiveQuery, values in their original text rather than URL-encoded, so a clause can be copied back into the parameter it came from
• All response values are strings (per SODA v2.1) — parse based on column type metadata
• domain selects the host contacted, data.cdc.gov (default) or chronicdata.cdc.gov — a four-by-four ID returns the same rows from either

cdc_query_wonder

Query CDC WONDER for national US mortality statistics — a separate CDC system from the Socrata datasets the other tools query.

database picks which of CDC's five mortality databases answers the query:

• Group results by any of year, age_group, sex, race (1–4 dimensions)
• Filter by ICD-10 underlying cause, sex, age groups, and year range
• age_groups carries the whole list CDC offers: the eleven ten-year groups plus NS, the group for a death whose age was not recorded. Listing the eleven without NS returns fewer deaths than the same query unfiltered, so include it to match an all-ages total or select it alone to count those deaths
• mcd_icd10 matches a cause recorded anywhere on the death certificate rather than only the one certified as underlying — "died with a respiratory condition listed", which no underlying-cause query can produce. Accepted only by the three databases marked above; the others reject it. A multiple-cause database queried without it returns the same figures as the underlying-cause database for the same years, and says so
• year_range carries the union of every database's span; a range outside the span of the one selected is rejected with that database's actual years named
• A race breakdown does not carry across the two race families — bridged race combines Asian and Pacific Islander into one group, single race splits them and adds a multiracial category, so the two series are not comparable
• Both cause filters also take 999--999, CDC's marker for deaths whose cause it is still withholding under the provisional database's six-month reporting lag. Only provisional records them; the other databases reject the code, and the tool says which one to select
• Row dimension values are CDC's own labels with surrounding whitespace removed, so the same year keys identically across databases — CDC pads a few of them, and "2024 " and "2024" would otherwise read as two different years
• Provisional rows carry CDC's own year labels, e.g. 2025 (provisional) and 2026 (provisional and partial), rather than a bare year
• Returns deaths, population, and crude death rate, plus age-adjusted rate when WONDER can standardize by age — omitted when grouping by age_group or filtering to a single age group
• Returns the whole table by default. A broad grouping runs long — ["year","age_group","sex","race"] can pass a thousand rows — so limit (max 5,000) and offset take it a page at a time, alongside totalCount, truncated, and a nextOffset to resume from. An offset at or past the row total returns an empty page rather than an error
• Paging shapes the response only: WONDER's request carries no limit of its own, so CDC is asked once either way and every page is a slice of the one table. caveats and messages come back complete on each page; cellNotes covers the rows returned, with row relative to them
• National totals only — sub-national (state/county) breakdowns are not available through the WONDER API (CDC vital-statistics policy)
• CDC replaces some measure values with a status token — Suppressed (withheld for confidentiality), Unreliable (a rate from fewer than 20 deaths), Not Applicable (no population denominator). Those cells read null in rows; cellNotes names the row, column, and token for each
• CDC also hides whole rows before sending the table — strata with zero deaths, and strata whose death count is suppressed. Those rows are absent from rows with nothing marking the gap, so messages carries CDC's own statement whenever it happened
• CDC rejects requests made less than 15 seconds apart, measured from the end of the previous response and counted across all five databases; the server spaces consecutive requests 16 seconds automatically

Resources and prompt

Features

Built on @cyanheads/mcp-ts-core:

• Declarative tool definitions — single file per tool, framework handles registration and validation
• Unified error handling across all tools
• Pluggable auth (none, jwt, oauth)
• Swappable storage backends: in-memory, filesystem, Supabase, Cloudflare KV/R2/D1
• Structured logging with optional OpenTelemetry tracing
• Runs locally (stdio/HTTP) or on Cloudflare Workers from the same codebase

CDC-specific:

• Wraps the Socrata SODA API v2.1 — no auth required, optional app token for higher rate limits
• Adds CDC WONDER mortality access (cdc_query_wonder) — national deaths, population, and crude/age-adjusted rates across five mortality databases spanning 1999 through the current year, final and provisional, underlying-cause and multiple-cause; a separate XML-over-HTTP CDC system
• Discovery-first approach for a heterogeneous catalog (~1,080 datasets across many health domains)
• Two CDC Socrata hosts via the domain input — data.cdc.gov (default) and chronicdata.cdc.gov, restricted to this allowlist. Both front one Socrata tenant: a single catalog whose assets — PLACES small-area estimates, the Heart Disease & Stroke Atlas and Environmental Public Health Tracking among them — are discoverable and queryable from either host
• Conservative request spacing for rate limit compliance (no rate-limit headers returned by Socrata)
• Handles SODA string-typed responses — all values returned as strings, parsed via column type metadata

Getting started

Public Hosted Instance

A public instance is available at https://cdc.caseyjhand.com/mcp — no installation required. Point any MCP client at it via Streamable HTTP:

{
  "mcpServers": {
    "cdc-health-mcp-server": {
      "type": "streamable-http",
      "url": "https://cdc.caseyjhand.com/mcp"
    }
  }
}

Self-Hosted / Local

Add the following to your MCP client configuration file.

{
  "mcpServers": {
    "cdc-health-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/cdc-health-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Or with npx (no Bun required):

{
  "mcpServers": {
    "cdc-health-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/cdc-health-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Or with Docker:

{
  "mcpServers": {
    "cdc-health-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/cdc-health-mcp-server:latest"]
    }
  }
}

For Streamable HTTP, set the transport and start the server:

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

Prerequisites

• Bun v1.3.2 or higher.
• Optional: Socrata app token for higher rate limits.

Installation

1. Clone the repository:

git clone https://github.com/cyanheads/cdc-health-mcp-server.git

1. Navigate into the directory:

cd cdc-health-mcp-server

1. Install dependencies:

bun install

Configuration

All configuration is validated at startup via Zod schemas in src/config/server-config.ts. Key environment variables:

Running the server

Local development

• Build and run the production version:

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

• Run checks and tests:

  bun run devcheck  # Lints, formats, type-checks, and more
  bun run test      # Runs the test suite
  

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

Contributing

Issues and pull requests are welcome. Run checks and tests before submitting:

bun run devcheck
bun run test

License

This project is licensed under the Apache 2.0 License. See the LICENSE file for details.