clinicaltrialsgov-mcp-server

---

概述

搜索 ClinicalTrials.gov 上的 60 多万项研究；该网站是美国国家医学图书馆的临床试验注册平台。获取完整研究记录和已发布的结果、发现字段及其有效值，并将患者资料与招募中的试验进行匹配。无需 API 密钥。

工具

工具	描述
clinicaltrials_search_studies	搜索研究，支持全文和特定字段查询、状态／阶段／地理位置筛选、分页、排序和字段选择
clinicaltrials_get_study_record	按 NCT ID 获取单项研究——完整方案记录，可选限制地点／结果／参考资料数量
clinicaltrials_get_study_count	快速获取查询对应的研究总数，无需获取数据
clinicaltrials_get_field_values	查找 API 字段的有效值，并显示各值对应的研究数量
clinicaltrials_get_field_definitions	查找有效字段名称——支持关键词搜索、逐级路径查询或顶层概览
clinicaltrials_get_study_results	获取已发布的结果——已完成研究的结局、不良事件、参与者流程和基线数据
clinicaltrials_find_eligible	根据患者的人口统计信息和病情匹配招募中的候选试验，不检查纳入／排除标准

资源

资源	描述
clinicaltrials://{nctId}	按 NCT ID 以 JSON 格式获取单项临床研究，其中列表数量有限，结果以计数代替

提示词

提示词	描述
analyze_trial_landscape	使用计数和搜索工具，引导开展数据驱动的临床试验概况分析

功能参考

clinicaltrials_search_studies _工具

• 支持自由文本 query，以及按字段指定的 conditionQuery / interventionQuery / locationQuery / sponsorQuery / titleQuery / outcomeQuery、枚举类型的 statusFilter / phaseFilter（接受大小写和空格格式的变体）、advancedFilter（AREA[FieldName]value / RANGE[min, max]）和 geoFilter（distance(lat,lon,radius)，带 mi/km 后缀）；pageSize 为 1–1000（默认 10；若超过服务端的单页上限，默认 200，则按上限返回一页，并附带 truncated / shown / cap）；pageToken 游标；最多可按 2 个字段进行 sort
• 默认返回每项研究的精简索引（nctId、briefTitle、overallStatus、phases、enrollmentCount、hasResults 等）；fields（PascalCase 叶字段）用于选择完整保真度的投影——完整记录约为 70 KB
• 类型化错误：blank_value、ids_not_found、field_invalid、enum_invalid、query_parse_error、geo_invalid、sort_invalid、page_token_invalid、rate_limited

---

clinicaltrials_get_study_record _工具

• 根据 nctId 获取完整方案记录，可选使用 locationLimit、outcomeLimit / referenceLimit，以及 nearLocation（lat、lon、radiusMi）对地点列表进行限制和排序——这些参数均无上限；若指定值超过列表长度，则返回整个列表
• 若上限截断了列表，filtersApplied 会报告上游总数；resultsSection 会替换为 resultsSummary 计数。类型化错误：study_not_found、rate_limited

---

clinicaltrials_get_study_count _工具

• 与 clinicaltrials_search_studies 使用相同的查询和筛选参数，仅返回 totalCount——不获取研究数据
• 类型化错误：blank_value、field_invalid、enum_invalid、query_parse_error、rate_limited

---

clinicaltrials_get_field_values _工具

• 支持一个或多个 PascalCase 格式的 fields（例如 OverallStatus、Phase）——返回每个字段的类型及其常见取值和对应的研究计数（API 上限为 250）；对于数值和日期字段，返回 min / max / avg；对于布尔字段，返回 trueCount / falseCount
• STRING 字段会额外返回其 longest 值；超过 2,000 个字符时会返回带有 truncated 标记的预览，并附上完整的 length，以及说明如何调用 clinicaltrials_search_studies 获取完整文本的提示。对于 API 不统计不同取值的自由文本字段，会设置 uniqueValuesCounted: false，表示其 uniqueValuesCount 为 0 并非实际计数
• multiValued 用于标记各取值计数总和可能超过研究总数的字段。类型化错误：blank_value、field_invalid、rate_limited

---

clinicaltrials_get_field_definitions _工具

• mode：search（关键词 query，limit 默认值为 20，无上限）、drill（点分隔表示法的 path）或 overview——用于解析 fields、advancedFilter、sort 和 clinicaltrials_get_field_values 接受的 PascalCase 名称
• 类型化错误：blank_value、mode_mismatch、mode_requires、path_not_found、rate_limited

---

clinicaltrials_get_study_results _工具

• 每次调用最多获取 20 个不同 nctIds 的结果；更多 ID（最多 500 个条目）会通过 deferredNctIds 返回；sections（outcomes、adverseEvents、participantFlow、baseline、moreInfo）；summary 用于精简单项研究结果集（可能超过 500 KB）；outcomeLimit / adverseEventLimit，以及可恢复的 outcomeOffset / seriousEventOffset / otherEventOffset
• 对每项研究分别返回 fetchErrors / studiesWithoutResults，而非导致整个批次失败；若别名 ID 解析为另一项研究，则返回 canonicalNctId。类型化错误：blank_value、offset_not_applicable、rate_limited

---

clinicaltrials_find_eligible _工具

• age（整数，0–120），可选 ageUnit（默认为 years，可选 months、weeks、days），适用于婴儿和年幼儿童；sex（FEMALE / MALE / ALL）；conditions[]；location（必填 country，可选 state / city）；healthyVolunteer；recruitingOnly（默认为 true）；maxResults（最多 1000；每次调用最多返回 50 条，其余条目通过 truncated / shown / cap 和可重放的 searchCriteria 予以说明）；locationLimit（无上限；如果设置的值大于匹配的地点数，则返回所有地点）
• 根据年龄、性别、地点、招募状态和模糊条件搜索进行匹配；funnel 会报告各筛选阶段的匹配数量，notice 会说明尚未检查纳入/排除标准（使用 clinicaltrials_get_study_record 查看）
• 类型化错误：blank_value、rate_limited

---

clinicaltrials://{nctId} _资源

• 完整的方案记录，格式为 application/json，地点、次要/其他结局和参考文献各最多 50 条——由服务端固定限制，无参数
• 结果数据将替换为 resultsSummary 计数；truncated 和 filtersApplied 会说明截断了哪些内容，retrieval 则列出获取完整数据的工具
• 类型化错误：study_not_found、rate_limited

---

analyze_trial_landscape _提示词

• 参数：必填 topic；可选 focusAreas（逗号分隔）
• 返回一条用户消息，指引 Agent 使用计数、搜索、字段发现和结果工具进行数据驱动的概况分析

功能

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

ClinicalTrials.gov 专属功能：

• 提供类型安全的 ClinicalTrials.gov REST API v2 客户端——公开使用，无需身份验证或 API 密钥
• 序列化请求队列，强制遵守 ClinicalTrials.gov 约每秒 1 次请求的速率限制；遇到 429/5xx 响应和 HTML 错误页面时会重试并采用指数退避
• 自动修正传入 fields/sort 的字段名（大小写、空格、RecruitmentStatus → OverallStatus 等旧别名），并记录每次修正
• 地理邻近搜索和最近地点重新排序，无需地理编码依赖
• 默认从搜索和计数中排除“未知”入组人数哨兵值（99999999）；includeUnknownEnrollment 可将其重新纳入

面向 Agent 的输出：

• 溯源信息——搜索、计数和资格工具会回显 searchCriteria；如果别名 ID 解析到另一项研究，clinicaltrials_get_study_results 会指出 canonicalNctId
• 优雅处理部分失败——clinicaltrials_get_study_results 会按研究返回 fetchErrors / studiesWithoutResults，而不是导致整个批次失败
• 类型化错误——每个工具都会返回 reason 代码（study_not_found、blank_value 等），有界列表仅在仍有更多条目时才会携带 next*Offset
• 响应裁剪——搜索和资格工具默认返回精简索引，而非约 70KB 的完整记录

开始使用

公共托管实例

公共实例位于 https://clinicaltrials.caseyjhand.com/mcp，无需安装。通过 Streamable HTTP 将任意 MCP 客户端指向该实例：

{
  "mcpServers": {
    "clinicaltrialsgov-mcp-server": {
      "type": "streamable-http",
      "url": "https://clinicaltrials.caseyjhand.com/mcp"
    }
  }
}

自托管 / 本地

将以下内容添加到 MCP 客户端配置文件中。

{
  "mcpServers": {
    "clinicaltrialsgov-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["clinicaltrialsgov-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

或使用 npx（无需 Bun）：

{
  "mcpServers": {
    "clinicaltrialsgov-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "clinicaltrialsgov-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

或使用 Docker：

{
  "mcpServers": {
    "clinicaltrialsgov-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/clinicaltrialsgov-mcp-server:latest"]
    }
  }
}

如需使用 Streamable HTTP，请设置传输方式并启动服务：

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

前置条件

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

安装

1. 克隆代码库：

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

2. 进入目录：

cd clinicaltrialsgov-mcp-server

3. 安装依赖：

bun install

配置

所有配置均为可选项——服务使用默认值即可运行，无需 API 密钥。

变量	说明	默认值
CT_API_BASE_URL	ClinicalTrials.gov API 基础 URL。	https://clinicaltrials.gov/api/v2
CT_REQUEST_TIMEOUT_MS	单次请求超时时间，单位为毫秒；必须为正整数。	30000
CT_MAX_PAGE_SIZE	clinicaltrials_search_studies 单页返回的研究数量上限；必须为 ≥ 1 的整数，超过 1000 的值会限制为 1000。	200
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	日志级别（RFC 5424）。	info
LOGS_DIR	日志文件目录（仅 Node.js）。	<project-root>/logs
OTEL_ENABLED	启用 OpenTelemetry 跟踪。	false
OTEL_EXPORTER_OTLP_ENDPOINT	用于跟踪和指标的 OTLP 基础 URL。	—
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT	用于导出日志的 OTLP 端点。	—
LOG_TOOL_FAILURE_PAYLOADS	记录每次失败的工具调用参数和结果，按键名进行脱敏，并限制在 LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES 字节以内（默认值为 16384）。自由格式值中的密钥不会脱敏。	false

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

运行服务

本地开发

• 构建并运行：

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

• 运行检查和测试：

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

Docker

docker build -t clinicaltrialsgov-mcp-server .
docker run --rm -p 3010:3010 clinicaltrialsgov-mcp-server

Dockerfile 默认使用 HTTP 传输、无状态会话模式，并将日志写入 /var/log/clinicaltrialsgov-mcp-server。默认会安装 OpenTelemetry 对等依赖项——构建时使用 --build-arg OTEL_ENABLED=false 可省略这些依赖项。

项目结构

目录	用途
src/index.ts	createApp() 入口点——注册工具、资源和提示词，并初始化 ClinicalTrials.gov 服务。
src/config	使用 Zod 解析和验证服务专用环境变量。
src/mcp-server/tools	工具定义（*.tool.ts）。
src/mcp-server/resources	资源定义（*.resource.ts）。
src/mcp-server/prompts	提示词定义（*.prompt.ts）。
src/services/clinical-trials	ClinicalTrials.gov REST API v2 客户端——重试、速率限制、字段搜索、类型。
tests/	单元测试和集成测试。

开发指南

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

• 处理程序抛出异常，由框架捕获——工具逻辑中不要使用 try/catch
• 使用 ctx.log 记录请求范围内的日志，不要调用 console
• 通过 src/mcp-server/*/definitions/index.ts 中的聚合导出文件注册新工具和资源
• 验证原始 API 响应，将其规范化为领域类型，绝不伪造缺失字段

贡献

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

bun run devcheck
bun run test

许可证

Apache-2.0——详情请参阅 LICENSE。