NHANES (design-correct survey analysis)

nhanes-mcp

用于以符合正确设计的方式对话式访问 NHANES 公开使用数据的 MCP 服务。 Black Swan Causal Labs · MIT 许可证 · v0.5 · PyPI · MCP 注册表

大多数“与数据集对话”的封装层会让 Agent 计算未加权均值。对于 NHANES，这样的结果是错误的。本服务将合理可靠的分析设为默认方式：Agent 用自然语言提出问题，服务便会查找文件、按 SEQN 合并数据、选取正确的权重、保留完整的调查设计，并报告基于调查设计的估计值及 NCHS 可靠性标记。

与 NCHS 或 CDC 无关，也未获其认可。 数据为美国国家卫生统计中心发布、直接从 cdc.gov 下载的 NHANES 公开使用文件。 用户有责任遵守 NCHS 数据使用协议。

它为你处理的常见问题

易错点	服务的处理方式
权重错误／缺少权重	build_dataset 会选取限制最严格的权重（访谈 → MEC → 空腹／静脉切开／剩余血清子样本 → 饮食第 1 天／第 2 天），说明原因，并将其存入 WT_ANALYSIS。每项结果都会注明权重覆盖设置（build_dataset(weight=...)、set_weight）；WT_ANALYSIS 不会被静默覆盖
估计前进行子集筛选	domain= 表达式会保留完整设计（域外权重设为零）
合并多个周期	按周期年数／总年数重新缩放权重（2017–2020 年 3 月计为 3.2 年）；1999–2002 年使用 4 年权重；分层编号按周期区分；拒绝 2017–2018 与 2017–2020 周期重叠
长格式表格（例如处方数据）	拒绝连接含有重复 SEQN 的表格（否则会静默重复权重）；flag_from_long_table 会将其折叠为每人一行
拒答／不知道代码	describe_variable 会读取 CDC 代码手册并建议哨兵代码；set_missing 会重新编码这些代码
缺失值被静默处理为 0	derive_variable 会传播缺失值（any / all / none）；coalesce、fillna、isna、notna、where 可有意处理缺失值
文件名不规则	会尝试已知变体（例如 1999–2000 年剩余血清文件 SSCMV_A、SSMUMP_A）
方差	Taylor 线性化、分层 × PSU、设计自由度；比例使用 Korn–Graubard 置信区间及 NCHS 2017 可靠性标记
年龄调整	直接调整至 2000 年美国标准（20–39 / 40–59 / 60+），并计算线性化标准误；也可调整至调用方提供的标准（年龄组 + 人口），若域内记录有年龄不在这些组中，则发出警告
死亡率	可选连接公开使用的关联死亡率文件（随访截至 2019 年），并进行基于调查设计的 Cox 模型分析

工具（17 个）

步骤	工具
了解概况	list_cycles、analysis_guidance
查找	list_files、search_variables、describe_variable
构建	build_dataset（可选连接死亡率数据）、describe_dataset
清理／派生	set_missing、derive_variable、flag_from_long_table、set_weight
分析	survey_frequency、survey_estimate、survey_regression（线性／逻辑回归）、survey_cox（Cox PH、Binder 方差）
展示	show_results — 文本 + 结构化结果；搭配可选的 Results Explorer 插件可交互查看
导出	export_dataset

周期：1999–2000 至 2017–2018、2017–2020 年 3 月（疫情前，P_ 文件），以及 2021 年 8 月至 2023 年 8 月。

结果探索器（可选附加组件）

show_results 会在每个客户端中以文本和结构化数据的形式返回基于调查设计的结果。安装可选的 NHANES Results Explorer 附加组件后，MCP Apps 宿主（Claude Desktop/web、ChatGPT、VS Code、Goose）还会呈现交互式视图：带有置信区间和 NCHS 可靠性徽章的核心估计值、会在服务端重新运行估计的粗略估计／年龄调整切换项、分析计划、亚组面板、服务端警告、与已发布估计值的基准比较，以及设计来源信息。

该附加组件是 Black Swan Causal Labs 发布的独立软件包，采用 PolyForm Noncommercial License 1.0.0（学术、公共卫生和其他非商业用途免费；商业用途需要许可证 — https://blackswancausallabs.com）。它不属于本 MIT 仓库。如果它安装在相同的 Python 环境中、NHANES_MCP_EXPLORER_PATH 指向它，或者名为 nhanes-mcp-explorer 的文件夹位于 nhanes-mcp 文件夹旁边，nhanes-mcp 就会找到它。

验证

已根据已发布的 NCHS 结果（validation/）检查估计值：

• **患病率：**57 项已发布的 NCHS 估计值中，57 项复现成功（Data Briefs 360、363、508、515；2015–2018 年合并数据；2017–2020 年 3 月疫情前数据）。
• **标准误：**20 项中有 20 项吻合；12 项已发布的 95% 置信区间界限中有 11 项完全一致（第 12 项在舍入边界处相差 0.1）。
• **死亡率：**对 NHANES 1999–2006 年数据（25 岁及以上成年人）进行基于调查设计的 Cox 模型分析，7 个已发布风险比中有 6 个复现结果落在其置信区间内（NHSR 155）。墨西哥裔美国人对比结果未能复现（0.71，而已发布值为 1.12）；目前正在调查这一问题，此处链接的文件随访时间更长（2019 年而非 2015 年）。
• 高血压（NCHS Data Brief 511，2021–2023 年，18 岁及以上成年人）：患病率（粗略估计和年龄调整，按性别和年龄划分）、知晓率、治疗率和控制率 — 17 项已发布估计值全部精确复现。
• CMV 血清阳性率（Bate et al., Clin Infect Dis 2010；NHANES 1999–2004 年，6–49 岁，剩余血清样本权重）：参见 tests/benchmark_nchs.py。在 v0.4 之前，服务端在此处会静默使用 MEC 权重，且无法加载 1999–2000 年文件。
• 单元测试（tests/）：将方差与独立的循环实现及逐一删除 PSU 的 Jackknife 方法进行比较；将 Cox 模型与 statsmodels PHReg 及 Jackknife 方法进行比较；并测试权重选择、合并、保护措施、表达式语义、长表和膳食权重处理。

安装

最简单的方法：让你的 AI 助手代劳

将以下内容粘贴到 Claude（Cowork 或 Claude Code），或任何能在你的电脑上运行命令的 Agent 中：

为 Claude Desktop 安装 nhanes-mcp MCP 服务（PyPI 软件包 nhanes-mcp）。如果缺少 uv，请先安装，然后将以下条目添加到我的 Claude Desktop 配置文件（claude_desktop_config.json）中，并使用 uvx 的完整路径："nhanes": {"command": "uvx", "args": ["nhanes-mcp"]}。 保留我现有的服务。然后提醒我重启 Claude Desktop。

在配置文件中添加一行（uvx）

安装 uv 后，将以下内容添加到 claude_desktop_config.json，然后重启 Claude Desktop （在 macOS 上，使用 which uvx 输出的完整路径，例如 /Users/<you>/.local/bin/uvx）：

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

首次启动时，uvx 会从 PyPI 获取服务并安装到隔离环境中；无需管理克隆仓库或虚拟环境。若要改为运行 GitHub 上的最新代码，请使用 "args": ["--from", "git+https://github.com/Black-Swan-Causal-Labs/nhanes-mcp", "nhanes-mcp"]。

从源代码安装（用于开发）

python3 -m venv ~/.nhanes-mcp-venv
~/.nhanes-mcp-venv/bin/pip install "mcp>=1.2,<2" pandas numpy scipy pyreadstat httpx beautifulsoup4 lxml
git clone https://github.com/Black-Swan-Causal-Labs/nhanes-mcp.git ~/nhanes-mcp

"nhanes": {
  "command": "/Users/<you>/.nhanes-mcp-venv/bin/python",
  "args": ["-m", "nhanes_mcp"],
  "env": {"PYTHONPATH": "/Users/<you>/nhanes-mcp"}
}

任何能运行本地 stdio 服务的 MCP 客户端都可以采用相同方式运行。数据会在首次使用时从 cdc.gov 下载，并缓存到 ~/.cache/nhanes-mcp（可通过 NHANES_MCP_CACHE 覆盖）。 将 NHANES_MCP_DATA_DIR 设置为存放手动下载的 .xpt 文件的文件夹，即可离线使用。

需要帮助为你的团队设置，或将其适配到其他调查或数据集？ 请联系 Black Swan Causal Labs。

测试

python tests/test_offline.py            # synthetic NHANES-shaped data, no network
python tests/test_cox.py
python tests/test_long_and_dietary.py
python tests/benchmark_nchs.py          # reproduces published NCHS estimates (needs network)

已知未解决问题

• 2009–2010 年及更早年份的年龄调整后成人肥胖率比 NCHS Health E-Stat 111 低 0.1–0.7 个百分点 （2011–2012 年起完全一致）。已排除合并数据和妊娠代码处理问题；原因仍在调查中。
• CMV 分析在公开的剩余血清文件中发现 14,198 名年龄为 6–49 岁的受检参与者，而 Bate 等人报告的数量为 15,310 人；原因不明。
• 不支持 NHANES III（1988–1994）。

更新日志

• 0.5.1 — 首次发布到 PyPI（uvx nhanes-mcp）和官方 MCP Registry （com.blackswancausallabs/nhanes-mcp）。仅更新打包元数据；分析无变化。
• 0.5.0 — 新增 show_results 工具（文本和结构化结果；可通过可选的 Results Explorer 插件查看交互视图）；支持使用 uvx 一键安装；新增分析指导规则 11。
• 0.4.1 — 现在，缺失值感知函数中的比较运算在某个操作数缺失时会返回缺失，因此，像 where(BPQ020 == 1, fillna(BPQ150, 2) == 1, 0) 这样的跳答模式定义，对于从未被询问筛查问题的人会返回缺失（而非 0）。新增高血压基准（NCHS Data Brief 511）。
• 0.4.0 — 检测并合并带有 2Y/4Y 后缀的剩余血清及其他特定文件的子样本权重；解决 1999–2000 年 _A 文件名问题；新增 build_dataset(weight=...) 和 set_weight 工具，两者都会记录在每项结果中；保护设计列不受 derive_variable 影响；新增缺失值感知表达式函数、自定义年龄标准和 CMV 基准。
• 0.3.0 — 首次公开发布。

限制

• 仅支持公开使用文件。受限使用数据（包括 NHANES–CMS Medicare/Medicaid 链接数据）需要通过 NCHS Research Data Center 获取。
• 方差采用泰勒线性化方法，并将 PSU 视为有放回抽样，与 NCHS 的建议一致；不使用重复权重。
• 服务会报告数据所能支持的内容；不会替你选择研究设计。