Ncbi Datasets

@pipeworx/ncbi-datasets

NCBI Datasets（美国国家医学图书馆）——查询某个生物有哪些基因组组装及其质量、某个基因的位置和它在其他数据库中的名称，以及 NCBI 分类树中每个节点的组装和基因数量。

属于 Pipeworx 的一部分——一个将 AI Agent 连接到 1683+ 个实时数据源的 MCP 网关。

工具

• ncbi_genome_reports(taxon?, accession?, reference_only?, assembly_level?, limit?) — 查询组装信息，包括组装级别、长度、contig/scaffold N50、GC%、提交者、 BioProject，以及配对的 RefSeq/GenBank 登录号。
• ncbi_gene_by_symbol(symbols, taxon?) — 查询 Entrez 基因 ID、生物类型、染色体、 RefSeqGene 坐标，以及 HGNC / Ensembl / UniProt / OMIM 交叉引用 和所有同义词。
• ncbi_taxonomy(taxons) — 将 tax ID、学名或俗名解析为 完整谱系、子节点、等级以及实时组装和基因数量。

认证

无需密钥。NCBI 会按 IP 对匿名调用者进行速率限制，在 api.ncbi.nlm.nih.gov 上约为每秒 5 次请求；该工具包会发送可识别身份的 User-Agent，不会重试，并会显示 429 错误及其说明，而不是不断循环请求。

与 ncbi-eutils 并非同一服务

E-utilities 是一个通用搜索/获取层，覆盖约 40 个 Entrez 数据库，并返回需要自行解析的记录。Datasets 则通过结构化行回答有关基因组、基因和分类学的结构化问题。对于这三类内容，请使用此工具包；对于 PubMed、dbSNP 和 Entrez 的其他内容，请使用 ncbi-eutils。

数据源

• https://api.ncbi.nlm.nih.gov/datasets/v2/genome/taxon/{taxon}/dataset_report
• https://api.ncbi.nlm.nih.gov/datasets/v2/genome/accession/{acc}/dataset_report
• https://api.ncbi.nlm.nih.gov/datasets/v2/gene/symbol/{symbols}/taxon/{taxon}
• https://api.ncbi.nlm.nih.gov/datasets/v2/taxonomy/taxon/{taxons}

值得记录、以免日后重新踩坑的事项（测于 2026-09-17）

• 不加筛选条件时，基因组报告会列出曾提交过的所有组装。 分类单元 562（大肠杆菌）有 492,559 条记录，而第一页的两条结果是同一组装的 GenBank/RefSeq 配对——从技术上说没错，但实际毫无用处。 filters.reference_only=true 会将结果减少到 2 条，因此 ncbi_genome_reports 在按分类单元查询时默认启用该筛选条件，并会说明这一点。
• 每个组装都有两份记录，分别为 GCA_（GenBank）和 GCF_（RefSeq）， 并通过 paired_accession 交叉链接。统计行数会导致组装数量翻倍。
• 包含多个值的路径不会保留顺序。 taxonomy/taxon/9606,10090 会先返回 Mus musculus。请根据返回的 query / symbol 进行匹配，切勿依赖位置。
• 基因报告中的数值字段是字符串（"gene_id":"672"），但分类学报告中是数字 （tax_id: 9606）。两种类型都会按接收时的形式传递。
• 分类单元路径接受 tax ID、学名或俗名—— 9606、Homo sapiens 和 human 均可使用。

快速开始

添加到你的 MCP 客户端（Claude Desktop、Cursor、Windsurf 等）：

{
  "mcpServers": {
    "ncbi-datasets": {
      "url": "https://gateway.pipeworx.io/ncbi-datasets/mcp"
    }
  }
}

此端点实际提供的内容

tools/list 在 https://gateway.pipeworx.io/ncbi-datasets/mcp 返回上表中的工具，以及 Pipeworx 共享元工具——ask_pipeworx、 discover_tools、search_within、remember/recall 及网关级的其他工具。因此，你看到的工具数量会多于此表：单个工具包端点目前会列出大约 30 个共享工具，以及该工具包自己的工具。连接的 initialize 响应会说明其确切范围，是当天权威的信息。

这是有意为之，并非意外复用多路连接。元工具让范围受限的连接也能回答此工具包未涵盖的问题——通过 ask_pipeworx 路由到整个目录——无需你再添加第二个 MCP 服务。目前无法挂载不含这些元工具的工具包端点；如果额外的架构所占用的上下文超过了路由带来的价值，请连接一次完整网关，而不是连接多个工具包端点。

或者，连接完整的 Pipeworx 网关，直接列出每个工具包的所有工具，而不只是此工具包的工具：

{
  "mcpServers": {
    "pipeworx": {
      "url": "https://gateway.pipeworx.io/mcp"
    }
  }
}

两个 URL 都连接到同一个网关和相同的 1683+ 个数据源。唯一的区别在于，哪个工具包的工具会被直接列出；ask_pipeworx 可从任一端点访问所有工具。

没有 MCP 客户端？通过 HTTP 调用

curl -X POST https://gateway.pipeworx.io/v1/tools/ncbi_genome_reports \
  -H 'Content-Type: application/json' \
  -d '{"taxon":"9606","limit":3}'

首次调用无需账户。查看任意工具：GET https://gateway.pipeworx.io/v1/tools/ncbi_genome_reports。查找工具：使用 {"query":"..."} 调用 POST https://gateway.pipeworx.io/v1/tools/search_packs。

独立运行（无需网关账户）

此软件包也可作为本地 stdio MCP 服务运行——无需 Pipeworx 账户，也无需经过网关往返：

{
  "mcpServers": {
    "ncbi-datasets": {
      "command": "npx",
      "args": ["-y", "@pipeworx/mcp-ncbi-datasets"]
    }
  }
}

也可以直接运行，以确认其能够启动：

npx -y @pipeworx/mcp-ncbi-datasets

它通过 stdin/stdout 使用 MCP，并为仅此工具包的工具响应 initialize/tools/list/tools/call——不包含上述网关连接额外提供的任何共享元工具。来源相同，工具相同，但没有 ask_pipeworx 路由。

使用 ask_pipeworx

你可以用通俗英语提问，而不是直接调用工具——此方式既适用于上述工具包端点，也适用于完整网关：

ask_pipeworx({ question: "your question about Ncbi Datasets data" })

网关会自动选择合适的工具并填写参数。

更多内容

• 文档和指南
• pipeworx.io

许可证

MIT