io.github.cyanheads/cdc-health-mcp-server

Official3 tools

by cyanheads · TypeScript

Search and query CDC public health data — mortality, vaccinations, surveillance, behavioral risk.

Search CDC public health data on mortality, vaccinations, disease surveillance, and behavioral risks.

Topics

cdchealth-datamcpmcp-servermodel-context-protocolpublic-healthsocratatypescriptcyanheads

Captured live from the server via tools/list.

cdc_discover_datasets

Search the CDC dataset catalog by keyword, category, or tag. Returns dataset IDs, names, truncated descriptions, column counts, and update timestamps. Use cdc_get_dataset_schema for the full column list of a chosen dataset.

Parameters (6)

domainstring
CDC Socrata portal to search. "data.cdc.gov" (default) is the main CDC catalog; "chronicdata.cdc.gov" hosts chronic-disease and small-area datasets (PLACES, the Heart Disease & Stroke Atlas, Environmental Public Health Tracking).
querystring
Full-text search across dataset names and descriptions (e.g., "diabetes mortality", "lead exposure children").
categorystring
Filter by domain category (e.g., "NNDSS", "Vaccinations", "Behavioral Risk Factors").
tagsarray
Filter by domain tags (e.g., ["covid19", "surveillance"]).
limitinteger
Results to return (default 10, max 100).
offsetinteger
Pagination offset for browsing beyond first page (max 9999).

cdc_get_dataset_schema

Fetch the full column schema for a CDC dataset — names, data types, descriptions, row count, and last-updated timestamp. Get dataset IDs from cdc_discover_datasets.

Parameters (2)

domainstring
CDC Socrata portal hosting the dataset. Use the same portal you found the dataset on via cdc_discover_datasets: "data.cdc.gov" (default) or "chronicdata.cdc.gov".
datasetIdstringrequired
Four-by-four dataset identifier (e.g., "bi63-dtpu"). Obtain from cdc_discover_datasets.

cdc_query_dataset

Execute a SoQL query against any CDC dataset. Supports filtering, aggregation, sorting, full-text search, and field selection. Use cdc_discover_datasets to find dataset IDs and cdc_get_dataset_schema to inspect columns before querying.

Parameters (10)

domainstring
CDC Socrata portal hosting the dataset. Must match the portal the dataset lives on: "data.cdc.gov" (default) or "chronicdata.cdc.gov" (PLACES and other chronic-disease/small-area datasets).
datasetIdstringrequired
Four-by-four dataset identifier (e.g., "bi63-dtpu"). Obtain from cdc_discover_datasets.
searchstring
Full-text search across all text columns. For precise filtering use the where parameter instead.
selectstring
SoQL SELECT clause — column names, aliases, or aggregates: "state, sum(deaths) as total_deaths". Omit for all columns. To enumerate distinct values of a column, set select to "{column}, count(*) as count" with group="{column}" and order="count DESC".
wherestring
SoQL WHERE clause. Strings must be single-quoted: "state='California' AND year=2020". If a column name matches a SoQL keyword (group, select, where, order, limit, offset, having, search), wrap it in backticks: "`group`='By Year'".
groupstring
SoQL GROUP BY clause. Requires aggregate functions in select.
havingstring
SoQL HAVING clause. Filters aggregated results.
orderstring
SoQL ORDER BY clause. Field name with optional ASC/DESC: "total_deaths DESC".
limitinteger
Max rows to return (default 100, max 5000).
offsetinteger
Row offset for pagination.

README.md10 KBView on GitHub

<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>3 Tools • 2 Resources • 1 Prompt</div> </p> </div> <div align="center">

</div> <div align="center">

Public Hosted Server: https://cdc.caseyjhand.com/mcp

</div>

Tools

Three tools for discovering and querying CDC public health data:

Tool	Description
`cdc_discover_datasets`	Search the catalog by keyword, category, or tag. Entry point for all queries.
`cdc_get_dataset_schema`	Fetch column schema, row count, and metadata for a dataset. Essential before writing SoQL queries.
`cdc_query_dataset`	Execute SoQL queries — filter, aggregate, sort, full-text search, and field selection.

`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"])
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
Pagination via offset for browsing large result sets
domain selects the portal: data.cdc.gov (default) or chronicdata.cdc.gov

`cdc_get_dataset_schema`

Fetch the full column schema for a specific dataset.

Column names, data types, and descriptions
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)
domain selects the portal hosting the dataset: data.cdc.gov (default) or chronicdata.cdc.gov

`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
Returns the assembled SoQL query string for debugging
All response values are strings (per SODA v2.1) — parse based on column type metadata
domain selects the portal hosting the dataset: data.cdc.gov (default) or chronicdata.cdc.gov

Resources and prompt

Type	Name	Description
Resource	`cdc://datasets`	Top 50 datasets by popularity for orientation
Resource	`cdc://datasets/{datasetId}`	Dataset metadata and column schema (equivalent to schema tool)
Prompt	`analyze_health_trend`	Guided 5-step workflow: discover, inspect, baseline query, compare, synthesize

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
Discovery-first approach for a heterogeneous catalog (~1,487 datasets across many health domains)
Two CDC Socrata portals via the domain input — data.cdc.gov (default) and chronicdata.cdc.gov (PLACES small-area estimates, the Heart Disease & Stroke Atlas, Environmental Public Health Tracking); restricted to this allowlist
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:

json

{
  "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.

json

{
  "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):

json

{
  "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:

json

{
  "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

Clone the repository:

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

Navigate into the directory:

cd cdc-health-mcp-server

Install dependencies:

bun install

Configuration

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

Variable	Description	Default
`MCP_TRANSPORT_TYPE`	Transport: `stdio` or `http`	`stdio`
`MCP_HTTP_PORT`	HTTP server port	`3010`
`MCP_AUTH_MODE`	Authentication: `none`, `jwt`, or `oauth`	`none`
`MCP_LOG_LEVEL`	Log level (`debug`, `info`, `warning`, `error`, etc.)	`info`
`LOGS_DIR`	Directory for log files (Node.js only)	`<project-root>/logs`
`STORAGE_PROVIDER_TYPE`	Storage backend: `in-memory`, `filesystem`, `supabase`, `cloudflare-kv/r2/d1`	`in-memory`
`CDC_APP_TOKEN`	Socrata app token for higher rate limits	none
`CDC_BASE_URL`	Base URL for SODA API requests	`https://data.cdc.gov`
`CDC_CATALOG_URL`	Base URL for Socrata Discovery API	`https://api.us.socrata.com/api/catalog/v1`
`OTEL_ENABLED`	Enable OpenTelemetry instrumentation (spans, metrics, completion logs)	`false`

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

Directory	Purpose
`src/mcp-server/tools`	Tool definitions (`*.tool.ts`). Three CDC data tools.
`src/mcp-server/resources`	Resource definitions. Catalog overview and dataset detail.
`src/mcp-server/prompts`	Prompt definitions. Health trend analysis workflow.
`src/services/socrata`	Socrata SODA API service layer — HTTP client, catalog search, metadata, queries.
`src/config`	Server-specific environment variable parsing and validation with Zod.

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.

Install

Configuration

Environment variables

CDC_APP_TOKEN

Socrata app token for higher rate limits.

MCP_LOG_LEVELdefault info

Sets the minimum log level for output (e.g., 'debug', 'info', 'warn').

MCP_HTTP_HOSTdefault 127.0.0.1

The hostname for the HTTP server.

MCP_HTTP_PORTdefault 3010

The port to run the HTTP server on.

MCP_HTTP_ENDPOINT_PATHdefault /mcp

The endpoint path for the MCP server.

MCP_AUTH_MODEdefault none

Authentication mode to use: 'none', 'jwt', or 'oauth'.

claude_desktop_config.json

{
  "mcpServers": {
    "cdc-health-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@cyanheads/cdc-health-mcp-server@0.7.0",
        "run",
        "start:stdio"
      ],
      "env": {
        "CDC_APP_TOKEN": "<YOUR_CDC_APP_TOKEN>",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}