NHANES (design Correct survey analysis)

What NHANES (design-correct survey analysis) MCP server does

NHANES (design-correct survey analysis) MCP server gives an MCP client tools for finding, preparing, analyzing, presenting, and exporting NHANES public-use data. It supports cycles from 1999–2000 through 2017–2018, the 2017–March 2020 pre-pandemic cycle, and August 2021–August 2023. NHANES III from 1988–1994 is not supported.

The workflow is intended to avoid common survey-analysis errors. Dataset construction chooses a suitable weight and records it as WT_ANALYSIS; domain expressions preserve the full sample design; pooled-cycle weights and strata are adjusted; and repeated-person long tables are rejected unless collapsed first. Missing-value handling, variable derivation, age adjustment, and optional linked mortality are also covered.

How it works

An agent can first inspect available cycles and analysis guidance, then search files and variables or read CDC codebook information. build_dataset downloads and combines selected files using SEQN, optionally joins the public-use Linked Mortality File through 2019, and prepares the design metadata. The server can retrieve known filename variants and refuses unsupported or unsafe combinations, including certain overlapping 2017–2018 and 2017–2020 selections.

Analysis tools use Taylor linearization with strata, PSUs, and design degrees of freedom. Available outputs include frequencies, estimates, linear and logistic regression, and a design-based Cox proportional-hazards model. Proportions can receive Korn–Graubard confidence intervals and NCHS 2017 reliability flags. Direct age standardization can use the 2000 US standard or caller-supplied age groups and populations.

Setup and configuration

The simplest installation uses uvx with the PyPI package:

{
  "nhanes": {
    "command": "uvx",
    "args": ["nhanes-mcp"]
  }
}

Add this entry to the MCP client configuration and restart the client. A GitHub source can be run through uvx --from, or developers can create a Python virtual environment, install the listed dependencies, clone the repository, and launch python -m nhanes_mcp with PYTHONPATH set to the checkout.

NHANES (design-correct survey analysis) MCP server downloads data from cdc.gov on first use and stores it under ~/.cache/nhanes-mcp. Set NHANES_MCP_CACHE to change the cache location. Set NHANES_MCP_DATA_DIR to use manually downloaded .xpt files and work offline. The optional Results Explorer package can be discovered through NHANES_MCP_EXPLORER_PATH or a neighboring nhanes-mcp-explorer directory; that add-on is separate from this MIT-licensed repository.

Tools and capabilities

The 17 tools are organized around the analysis lifecycle:

• Orientation: list_cycles, analysis_guidance
• Discovery: list_files, search_variables, describe_variable
• Dataset construction: build_dataset, describe_dataset
• Cleaning and derivation: set_missing, derive_variable, flag_from_long_table, set_weight
• Analysis: survey_frequency, survey_estimate, survey_regression, survey_cox
• Results and export: show_results, export_dataset

show_results always returns text and structured results. When the separate Results Explorer is installed, supported MCP Apps hosts can also display confidence intervals, reliability badges, subgroup panels, warnings, benchmarks, provenance, and crude versus age-adjusted views.

Limitations and notes

NHANES (design-correct survey analysis) MCP server is not affiliated with or endorsed by NCHS or CDC, and users remain responsible for the NCHS data-use agreement. Validation covers many published estimates, but the README identifies unresolved discrepancies: some older age-adjusted adult-obesity estimates run below Health E-Stat values, and one CMV comparison has fewer tested participants than a published study. A Mexican American mortality contrast also does not reproduce the cited published result and remains under investigation.

The linked mortality data provide follow-up through 2019. Commercial use of the optional Results Explorer requires a separate license under its PolyForm Noncommercial License 1.0.0; that license does not apply to the MIT repository.