cdc-health-mcp-server

<div align="center">
  <h1>@cyanheads/cdc-health-mcp-server</h1>
  <p><b>Search and query CDC public health data — mortality, vaccinations, surveillance, behavioral risk (Socrata SODA API) via MCP. STDIO or Streamable HTTP.</b>
  <div>5 Tools • 2 Resources • 1 Prompt</div>
  </p>
</div>

<div align="center">

[![Version](https://img.shields.io/badge/Version-0.10.0-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/cdc-health-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^2.3.1-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/cdc-health-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/cdc-health-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^7.0.2-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.4.3-blueviolet.svg?style=flat-square)](https://bun.sh/)

</div>

<div align="center">

[![Install in Claude Desktop](https://img.shields.io/badge/Install_in-Claude_Desktop-D97757?style=for-the-badge&logo=anthropic&logoColor=white)](https://github.com/cyanheads/cdc-health-mcp-server/releases/latest/download/cdc-health-mcp-server.mcpb) [![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=cdc-health-mcp-server&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBjeWFuaGVhZHMvY2RjLWhlYWx0aC1tY3Atc2VydmVyIl19) [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=for-the-badge&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect?url=vscode:mcp/install?%7B%22name%22%3A%22cdc-health-mcp-server%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40cyanheads%2Fcdc-health-mcp-server%22%5D%7D)

[![Framework](https://img.shields.io/badge/Built%20on-@cyanheads/mcp--ts--core-67E8F9?style=flat-square)](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)

</div>

<div align="center">

**Public Hosted Server:** [https://cdc.caseyjhand.com/mcp](https://cdc.caseyjhand.com/mcp)

</div>

---

## Overview

CDC public health data from two systems: the Socrata-based CDC Open Data portal and CDC WONDER, a separate CDC system for national mortality statistics. Search the catalog, inspect dataset schemas, and run SoQL queries across vaccination, surveillance, and behavioral-risk data, or query WONDER for deaths, population, and death rates by year, age, sex, and race. Runs as a stdio process, a local Streamable HTTP server, or the public hosted endpoint above.

### Tools

| Tool | Description |
|:---|:---|
| `cdc_discover_datasets` | Search the CDC dataset catalog by keyword, category, or tag |
| `cdc_get_dataset_schema` | Fetch column schema, row count, and metadata for a dataset |
| `cdc_list_catalog_vocabulary` | List the catalog's category and tag values with their entry counts |
| `cdc_query_dataset` | Execute SoQL queries — filter, aggregate, sort, full-text search, select fields |
| `cdc_query_wonder` | Query CDC WONDER for national mortality, population, and death rates across five databases |

### Resources

| Resource | Description |
|:---|:---|
| `cdc://datasets` | Top 50 most-viewed catalog entries, for orientation |
| `cdc://datasets/{datasetId}` | 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 |
|:---|:---|
| `analyze_health_trend` | Guided workflow for investigating a public health question across CDC data |

## Capability reference

### `cdc_discover_datasets` <sub>tool</sub>

- `query`, `category`, and `tags` filters (tags union, the other two intersect with them); up to 100 results per page (default 10; a larger `limit`, up to 10,000, is capped at 100 and the `notice` says so with the offset to continue from), with `offset + limit` capped at 10,000 (`page_out_of_range` past it); `order` is `dataset_id` (default, stable paging) or `relevance`
- Results carry `assetType`, `columnCount` (0 marks a chart, map, story, file, or link that yields no data), an 8-name `columnSample`, and a description cut to 300 characters (`cdc_get_dataset_schema` with `full_description: true` returns the whole text); enrichment adds `totalCount` and `appliedFilters`
- 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` <sub>tool</sub>

- Four-by-four `datasetId` (e.g. `bi63-dtpu`); `column_limit` (default 100, any larger value up to the whole schema) and `column_offset` page wide schemas, reporting `totalCount`, `truncated`, and `nextOffset`
- The dataset `description` is capped at 4,000 characters by default, ending in `…` with `descriptionTruncated` and `descriptionLength` set when cut; `full_description: true` returns the whole text. Column descriptions are never shortened
- Columns carry `fieldName`, `dataType`, and `description`; `rowCountSource` says whether `rowCount` is a `live` count or Socrata's `cached` figure, which can lag an active dataset. A non-tabular asset fails with `not_queryable`

---

### `cdc_list_catalog_vocabulary` <sub>tool</sub>

- Every category comes back whole; the ~1,600 tags are ranked by entry count and paged with `tag_limit` (default 50; a value at or above the tag count returns them all) and `tag_offset`. `filter` (3+ characters) narrows both by word containment in either direction, not fuzzy matching
- Each value carries `datasetCount`; enrichment reports `vocabularySize`, `categoryCount`, `tagCount`, `truncated`, and `nextOffset`, with `truncationCeiling` bounding the count of every tag after the page — the tags before `tag_offset` rank at or above the first tag shown

---

### `cdc_query_dataset` <sub>tool</sub>

- `select`, `where`, `group`, `having`, `order`, and full-text `search`; up to 5,000 rows per call (default 100; a larger `limit` is capped at 5,000 and says so), `offset` up to 1,000,000. Pair offset paging with an `order`, set from the first page, ending in a per-row tie-breaker: `:id` on ungrouped rows, the grouped columns on a grouped query. When the order lacks one, the notice says to restart from offset 0 with it
- `effectiveQuery` echoes the SoQL clauses as sent, unencoded; `truncated` and `nextOffset` come from a one-row over-fetch, with no `totalCount`. A chart or map ID fails with `not_queryable`

---

### `cdc_query_wonder` <sub>tool</sub>

| `database` | CDC database | Years | Race groups | `mcd_icd10` |
|:---|:---|:---|:---|:---|
| `underlying_1999_2020` *(default)* | D76 — Underlying Cause of Death | 1999–2020 | 4 bridged | — |
| `provisional` | D176 — Provisional Mortality Statistics | 2018 → current year | 6 single-race | yes |
| `underlying_2018_2024` | D158 — Underlying Cause of Death, Single Race | 2018–2024 | 6 single-race | — |
| `multiple_1999_2020` | D77 — Multiple Cause of Death | 1999–2020 | 4 bridged | yes |
| `multiple_2018_2024` | D157 — Multiple Cause of Death, Single Race | 2018–2024 | 6 single-race | yes |

- `group_by` takes 1–4 of `year`, `age_group`, `sex`, `race`, national only. `cause_icd10` and `mcd_icd10` take an ICD-10 code, a chapter or block range (`X40-X49`), or a list of up to 50 matched as one union (an empty list reads as all causes). `age_groups` takes `NS` (age not stated) alone or with all eleven known groups, never beside only some of them, which CDC refuses. `limit` (any positive integer; the response budget bounds the page) and `offset` (max 10,000) page the table, and an empty page's notice says whether nothing matched or the offset ran past the end
- Rows carry `deaths`, `population`, `crude_rate`, and `age_adjusted_rate` where age can be standardized. Cells CDC returns as `Suppressed`, `Unreliable`, or `Not Applicable` read `null` and are listed in `cellNotes`; `messages` reports whole rows CDC hid, and `totalCount` is exact
- CDC rejects requests less than 15 seconds apart, so calls are spaced 16 seconds apart and queued one at a time

---

### `cdc://datasets` <sub>resource</sub>

- 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}` <sub>resource</sub>

- Dataset metadata plus the first 100 columns as `application/json`, with `columnCount` and `truncated`; the description is capped at 4,000 characters, with `descriptionTruncated` and `descriptionLength` set when cut
- Takes no selector; continue a wider schema with `cdc_get_dataset_schema` and `column_offset`, and read a cut description whole with its `full_description: true`. The `notice` names both when they apply

---

### `analyze_health_trend` <sub>prompt</sub>

- 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`](https://github.com/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](https://dev.socrata.com/) over the CDC