openfda-mcp-server

---

概述

通过 openFDA 公共 API 获取药品、食品、器械和召回数据。搜索不良事件、召回、药品批准和器械许可；查询 NDC 代码和药品标签；聚合任意端点的字段计数。

工具

工具	描述
openfda_drug_profile	输入一个药品名称 → 汇总的 FDA 资料：身份信息、标签、不良事件、召回、批准和短缺
openfda_search_adverse_events	搜索药品、食品和器械的不良事件报告
openfda_search_animal_events	搜索兽用药品和器械的不良事件报告
openfda_search_drug_shortages	按状态、可获得性、治疗类别和制造商搜索 FDA 药品短缺记录
openfda_search_tobacco_reports	搜索烟草制品、电子烟和雾化设备的问题报告
openfda_search_recalls	搜索药品、食品和器械的执法报告及召回行动
openfda_count_values	汇总并统计任意 openFDA 端点中任意字段的唯一值
openfda_describe_fields	返回 openFDA 端点的可搜索字段路径，并按类别分组
openfda_get_drug_label	查询 FDA 药品标签（包装说明书 / SPL 文档）
openfda_search_drug_approvals	搜索 Drugs@FDA 数据库中的 NDA/ANDA 申请批准信息
openfda_search_device_clearances	搜索 FDA 器械上市前通知：510(k) 许可和 PMA 批准
openfda_lookup_ndc	在 NDC（国家药品代码）目录中查询药品
openfda_dataframe_describe	列出已暂存到 DataCanvas 的表和列架构
openfda_dataframe_query	对暂存到 DataCanvas 的结果集运行只读 SQL
openfda_dataframe_drop	删除一个暂存到 DataCanvas 的表（需主动启用，默认关闭）

功能参考

openfda_drug_profile _工具

• 输入一个 drug 名称（品牌名或通用名），解析一次以确定其身份信息（通用名、NDC、RxCUI、SPL 集 ID）；召回、批准和短缺信息以 meta.fanOutKey 为键——当输入名称是已解析通用名的某种成分时使用该名称，否则使用通用名；meta.resolvedVia（label、ndc、none）表示信息来源，并优先选择单一成分产品而非复方产品
• 召回和批准查询也会搜索 openFDA 从未统一过的记录（product_description、products.active_ingredients.name）；recalls_total 会在最新 5 条召回记录旁给出匹配数
• label、adverse_events、recalls、approval 和 shortage 部分尽力返回结果，未找到时返回 null（或空的 recalls）；degraded[] 会列出上游子查询失败的部分，因此列出的部分表示未知，而不是不存在
• 身份验证、配置和取消错误会导致整个调用失败，而不会仅使某个部分降级

---

openfda_search_adverse_events _工具

• category（drug、food、device）用于选择端点及其记录架构；每页最多 1000 条记录
• 可排序的日期字段因类别而异：receivedate（药品）、date_created（食品）、date_received（器械）；使用其他类别的字段会导致 query_error
• 文本输出会在原始值旁解码药品给药途径、反应结局和患者年龄组代码（via oral (048)、fatal (5)、elderly (6)）；结构化输出保留这些代码

---

openfda_search_animal_events _工具

• 可选地使用 search 搜索兽医报告，例如 animal.species、drug.active_ingredients.name、reaction.veddra_term_name、serious_ae；每页最多 1000 条记录
• 每条记录中的品牌名和制造商名称都会被屏蔽为 MSK，因此请按活性成分搜索；drug.manufacturer.registration_number 可将结果缩小到某个批准
• 记录包含动物种类、品种、年龄和体重、药品及给药途径、VeDDRA 反应术语和结局

---

openfda_search_drug_shortages _工具

• 可选地按 status（Current / To Be Discontinued / Resolved）、therapeutic_category、generic_name 或 company_name 进行 search；每页最多 1000 条记录
• 每条记录的 openfda 块包含 brand_name、product_ndc 和 rxcui，可用于接续调用 openfda_get_drug_label 或 openfda_lookup_ndc

---

openfda_search_tobacco_reports _工具

• 可选地按 tobacco_products、reported_health_problems、reported_product_problems 或 nonuser_affected 进行 search；每页最多 1000 条记录
• 报告包含问题数组以及 number_tobacco_products、number_health_problems 和 number_product_problems 计数

---

openfda_search_recalls _工具

• category（drug、food、device）以及 endpoint：enforcement（默认，适用于所有类别）或 recall（仅适用于设备；其他类别会以 recall_endpoint_non_device 失败）；每页最多 1000 条记录
• Enforcement 记录包含 recall_number、classification（Class I/II/III）和 status；设备召回记录则包含 product_res_number 和 recall_status，不含危害分类

---

openfda_count_values _工具

• endpoint（20 个 openFDA endpoint 中的任意一个）、count 字段表达式以及可选的 search；返回最多 1000 个热门词项（默认 100 个），按计数排序；日期字段会为每个不同的 YYYYMMDD 日期返回一个词项，排序方式相同
• 如果存在超出 limit 的不同词项，truncated 会标记这一情况；但达到 1000 个词项的上限时，会显示无法确定数据是否完整的提示（日期计数在任何 limit 下都是精确的，因为 openFDA 会发送每个日期）；如果 openFDA 无法聚合某个表达式，则会以 not_aggregatable 失败（请从 openfda_describe_fields 获取 countAs 格式）
• 即使启用了 bulk 镜像，也始终通过实时 API 执行

---

openfda_describe_fields _工具

• endpoint：与 openfda_count_values 接受的 20 个 endpoint 相同
• 按类别分组的字段路径；每个字段都包含 type、描述和 countAs（已验证的计数表达式；字段无法聚合时为 null），以及关于引号、AND/OR、.exact 和日期范围的 queryTips

---

openfda_get_drug_label _工具

• 必须在标签字段（openfda.brand_name、openfda.generic_name、openfda.manufacturer_name、set_id）上执行 search；limit 默认值为 5，最大值为 1000
• 如果某页超过 24,000 字节的内联预算，则会返回 kind: "outline"（按大小从大到小排列的章节名称和大小），而不是标签文本；再次调用并传入 sections: [...]，即可获取这些章节以及身份元数据（openfda、set_id、id、effective_time、version），即使超出预算也会完整返回
• *_table 章节在文本输出中会渲染为 Markdown 表格；结构化结果则保留原始 SPL 标记

---

openfda_search_drug_approvals _工具

• 可选地按 openfda.brand_name、sponsor_name（以大写形式存储，因此带引号的小写值不会匹配任何内容）、submissions.submission_type 或 submissions.review_priority 进行 search；每页最多 1000 条记录
• 记录包含 application_number、sponsor_name、products[] 以及该申请的完整 submissions[] 历史记录

---

openfda_search_device_clearances _工具

• pathway（510k 或 pma，每次调用只能指定一个）以及可选的 search，可按 applicant、product_code、advisory_committee_description 或 openfda.device_name 搜索；每页最多 1000 条记录
• 510(k) 记录包含 k_number、device_name 和 decision_date；PMA 记录包含 pma_number、trade_name 和 supplement_number

---

openfda_lookup_ndc _工具

• 必须按 product_ndc、brand_name、generic_name、openfda.manufacturer_name 或 active_ingredients.name 进行 search；每页最多 1000 条记录
• 记录包含 product_ndc、labeler_name、dosage_form、route、marketing_category、active_ingredients[] 和 packaging[]

---

openfda_dataframe_describe _工具

• 使用暂存搜索中的 canvas_id；列出每个表的 name、kind、完整暂存 row_count，以及包含 DuckDB 类型和是否可为 null 的列
• 当 CANVAS_PROVIDER_TYPE=none 时失败并返回 canvas_disabled；当 canvas_id 已过期或从未存在时失败并返回 canvas_not_found

---

openfda_dataframe_query _工具

• 使用 canvas_id 和一条只读 SELECT；不允许 DDL、DML、COPY 和文件读取函数。标量以文本形式存储（数学运算需使用 CAST），嵌套的 openFDA 数据块以 JSON 列存储
• 行数上限为 canvas 行数限制；truncated: true 表示需要使用 ORDER BY 和 LIMIT/OFFSET 继续分页；失败时返回 canvas_disabled、canvas_not_found、missing_table 或 invalid_query

---

openfda_dataframe_drop _工具

• 默认关闭：设置 OPENFDA_DATAFRAME_DROP_ENABLED=true 后即可调用；否则该工具会在着陆页上标记为已禁用，且不会出现在 tools/list 中
• 使用 canvas_id 和 openfda_dataframe_describe 返回的 table 名称；删除该表或视图，并返回 remaining_tables，canvas 和其中其他表会保留
• 失败时返回 canvas_disabled、canvas_not_found 或 missing_table（已删除、已过期或名称拼写错误）

功能

基于 @cyanheads/mcp-ts-core 构建：支持 stdio 和 Streamable HTTP 传输、可插拔身份验证（none / jwt / oauth）、可切换存储（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1），并提供结构化日志记录和可选的 OpenTelemetry 跟踪。

openFDA 专属功能：

• 一个客户端支持全部 20 个 openFDA 端点，遇到 429 和 5xx 时会重试。无需 API 密钥（每天 1K 次请求）；免费的 OPENFDA_API_KEY 可将限额提升至每天 120K 次
• 查询使用点分路径，并以 AND/OR 连接 field:value 条件（子句之间 URL 风格的 + 会被视为空格）；openfda_describe_fields 会列出路径，格式错误的查询会在发起请求前以 malformed_search 失败
• 分页：limit 最高为 1000，skip 最高可达 openFDA 的 25,000 条记录上限（超过后返回 pagination_limit_reached）；每页大小限制为 24,000 字节
• 在任何 openfda_search_* 工具或 openfda_lookup_ndc 中使用 fields，可按指定的点分路径裁剪每条记录，使大型记录也能以内联形式返回
• DataCanvas 暂存（默认开启；设置 CANVAS_PROVIDER_TYPE=none 可关闭），可使用 stage: true 或 canvas_id；还可选配本地批量镜像（OPENFDA_MIRROR_ENABLED=true），对精确键查找进行响应而不消耗 API 配额

便于 Agent 使用的输出：

• 明确披露边界：page_omitted、page_bytes、page_largest_fields、projected_fields、标签 outline 和 staged_rows 会报告所有截断情况
• 带类型的失败：调用方可根据 error.data.reason（rate_limited、query_error、not_aggregatable 等）进行分支处理，而无需解析消息
• 区分未知与不存在：对于没有 FDA 记录的部分，openfda_drug_profile 会返回 null，并在 degraded[] 中列出失败的部分
• 空结果指引：搜索无匹配结果时，会提示查看 openfda_describe_fields 并尝试更宽泛的搜索词

开始使用

连接到托管实例，无需安装：

claude mcp add --transport http openfda-mcp-server https://openfda.caseyjhand.com/mcp

或在本地运行：

claude mcp add openfda-mcp-server -- npx -y @cyanheads/openfda-mcp-server

对于其他客户端，请将以下内容添加到 MCP 配置文件：

{
  "mcpServers": {
    "openfda-mcp-server": {
      "command": "npx",
      "args": ["-y", "@cyanheads/openfda-mcp-server"]
    }
  }
}

无需 API 密钥。将免费的 openFDA API 密钥 设置为 OPENFDA_API_KEY，可将限额从每天 1K 次请求提升至 120K 次。Docker 或源码构建方式请参阅运行服务。

配置

变量	说明	默认值
OPENFDA_API_KEY	从 open.fda.gov 获取的免费 API 密钥；每日限额从 1K 次请求提高至 120K 次。	none
OPENFDA_BASE_URL	API 基础 URL 覆盖值，用于代理或模拟服务。	https://api.fda.gov
OPENFDA_MIRROR_ENABLED	从本地批量镜像响应精确键查找。	false
OPENFDA_MIRROR_PATH	存放每个镜像数据集对应 SQLite 文件的目录。	./data/openfda-mirror
OPENFDA_MIRROR_REFRESH_CRON	进程内镜像刷新的 Cron 表达式（仅限 HTTP 传输）。	none
OPENFDA_MIRROR_FALLBACK_LIVE	镜像尚未就绪、缺少记录或发生故障时，回退到实时 API。	true
OPENFDA_MIRROR_REFRESH_TIMEOUT_MS	单次刷新被中止前的墙钟时间预算，单位为 ms。	21600000 (6h)
OPENFDA_MIRROR_BASE_URL	提供批量下载清单（download.json）的主机。	https://api.fda.gov
CANVAS_PROVIDER_TYPE	DataCanvas 暂存和 SQL。none 会禁用这些功能；数据框工具仍会列出，但会返回 canvas_disabled。	duckdb
OPENFDA_DATAFRAME_DROP_ENABLED	启用 openfda_dataframe_drop，用于删除暂存表。需要 CANVAS_PROVIDER_TYPE=duckdb。	false
MCP_TRANSPORT_TYPE	传输方式：stdio 或 http。	stdio
MCP_HTTP_PORT	HTTP 服务端口。	3010
MCP_SESSION_MODE	HTTP 会话模式：stateless、stateful 或 auto。	stateless
MCP_AUTH_MODE	身份验证：none、jwt 或 oauth。	none
MCP_LOG_LEVEL	日志级别（debug、info、warning、error 等）。	info
LOGS_DIR	日志文件目录（仅 Node.js）。	<app-root>/logs
STORAGE_PROVIDER_TYPE	存储后端：in-memory、filesystem、supabase、cloudflare-kv/r2/d1。	in-memory
OTEL_ENABLED	启用 OpenTelemetry。	false

完整的可选覆盖项列表请参见 .env.example。

Claude Desktop MCPB 包会禁用 DataCanvas，因为其中不包含特定于平台的 DuckDB 绑定。要使用暂存和 SQL，请使用 npm 或 Docker。

本地批量镜像

设置 OPENFDA_MIRROR_ENABLED=true 后，服务会在本地保留四个 openFDA 批量数据转储（drug/label、drug/ndc、drug/enforcement、drug/drugsfda）的 SQLite 副本。只有精确查找会在本地响应：单个带引号的 field:"value" 条件，字段为 id、set_id、product_id、product_ndc、recall_number、event_id 或 application_number；不带 count 或 sort，skip 为 0，且只有一条匹配记录。其他所有请求都会转发到 API。

初始数据抓取会单独运行，不会在启动时执行：

bun run mirror:init                  # all four datasets
bun run mirror:init drug/enforcement # one dataset
bun run mirror:status                # sync state per dataset
bun run mirror:verify                # integrity check + row counts
bun run mirror:refresh               # re-harvest datasets whose dump has advanced

刷新会重新读取整个数据转储。设置 OPENFDA_MIRROR_REFRESH_CRON，即可通过 HTTP 传输在进程内运行刷新；使用 stdio 时，请在宿主机上运行 bun run mirror:refresh。镜像响应中的 meta.lastUpdated 是所提供数据转储的时间戳，可能与实时 API 中的时间戳不同。

在 Node 上，请安装可选的 better-sqlite3 对等依赖（Bun 使用内置的 bun:sqlite）。OPENFDA_MIRROR_REFRESH_CRON 还需要可选的 node-cron 对等依赖；未安装时，服务会在启动时失败。

运行服务

本地开发

需要 Bun v1.4.0 或更高版本（或 Node.js v24+）。

• 克隆并安装：

  git clone https://github.com/cyanheads/openfda-mcp-server.git
  cd openfda-mcp-server && bun install
  cp .env.example .env   # optionally set OPENFDA_API_KEY and the mirror or canvas options
  

• 构建并运行：

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

• 运行检查和测试：

  bun run devcheck   # Lint, format, typecheck, security
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec
  

Docker

docker run --rm -p 3010:3010 ghcr.io/cyanheads/openfda-mcp-server:latest

该镜像默认使用 HTTP 传输、无状态会话模式，并将日志写入 /var/log/openfda-mcp-server。若要通过 MCP 客户端使用 stdio 运行，请使用 "command": "docker" 和 "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/openfda-mcp-server:latest"]。若要在本地构建，运行 docker build -t openfda-mcp-server .；默认会安装 OpenTelemetry 对等依赖，若要省略这些依赖，请使用 --build-arg OTEL_ENABLED=false 构建。若要在容器更换后保留镜像采集的数据，请在 /usr/src/app/data/openfda-mirror 上挂载卷。

项目结构

目录	用途
src/index.ts	createApp() 入口：工具注册、服务设置、镜像刷新配置。
src/config	使用 Zod 解析并验证特定于服务的环境变量。
src/mcp-server/tools/definitions	工具定义（*.tool.ts），共 15 个。
src/mcp-server/tools	共享工具辅助模块：各端点的字段目录、输入模式和校验逻辑、格式化程序、SPL 表格渲染。
src/services/openfda	openFDA API 客户端（重试、速率限制、错误规范化）、内联页面预算、fields 记录投影、canvas 暂存。
src/services/openfda/mirror	可选的本地批量镜像：数据集注册表、转储读取器、采集器、镜像与实时查询的选择逻辑、刷新计划。
src/services/canvas	用于暂存和 SQL 的 DataCanvas 访问器。
scripts/openfda-mirror.ts	由 mirror:* 脚本调用的镜像生命周期 CLI。
tests/	单元测试和集成测试，结构与 src/ 对应。

开发指南

开发指南和架构规则请参阅 CLAUDE.md。简要说明：

• 处理程序抛出错误，由框架捕获；工具逻辑中不要使用 try/catch
• 使用 ctx.log 记录请求范围内的日志
• 在 src/mcp-server/tools/definitions/index.ts 的汇总入口中注册新工具
• 封装外部 API 调用：校验原始数据 → 规范化为领域类型 → 返回输出模式；绝不编造 openFDA 未返回的字段

数据归属说明

数据来自 openFDA，这是美国食品药品监督管理局的一项服务。根据 openFDA 许可，这些数据依据 CC0 1.0 许可奉献给公有领域，但有一个例外：GMDN® 设备分类内容（Term Code、Term Name 和 Term Definition）由 The GMDN Agency 授权；重新分发这些内容或将其用于训练 AI，均需获得该机构的单独许可。

因此，本地镜像仅涵盖药品数据集。device/classification 和所有其他设备端点均不包含在镜像中；摄取程序也会拒绝任何带有 GMDN 相关字段的记录，不会将其写入磁盘。

FDA 不为本项目背书。请勿依赖 openFDA 来做出医疗护理相关决定。

贡献

欢迎提交问题。提交前请运行检查和测试：

bun run devcheck
bun run test

许可证

本项目采用 Apache 2.0 许可证。详情请参阅 LICENSE 文件。