Ucsc Genome

@pipeworx/ucsc-genome

来自 UCSC Genome Browser 的参考基因组组装——某个物种有哪些组装版本，每个版本包含哪些注释轨道，任意基因组区间内轨道的实际行数据，以及原始参考 DNA。

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

工具

• ucsc_genomes(search?, limit?) — UCSC 的所有组装版本（约 238 个），包含组装 ID（hg38、mm39、danRer11）、生物体、学名、来源组装和版本说明。其他所有调用都依赖这里获取的 ID。
• ucsc_tracks(genome, search?, limit?) — 一个组装版本上的注释轨道，包含 ucsc_track_data 所需的内部轨道名称。浏览器 UI 显示的是标签，而非名称：“GENCODE V50”对应的轨道是 knownGene，两者之间没有固定映射规则。
• ucsc_track_data(genome, track, chrom, start, end, maxItemsOutput?) — 某个区间内的轨道行数据：基因模型及外显子结构、ClinVar 变异、重复序列，或该轨道包含的其他数据。
• ucsc_sequence(genome, chrom, start, end, revComp?) — 某个区间的参考 DNA，包含 GC 比例和 N 的数量。

身份验证

无需密钥。无需注册，未观察到速率限制标头。UCSC 建议高频用户使用镜像或本地安装，而不是频繁请求公共端点，因此请合理控制区间宽度。

数据来源

• https://api.genome.ucsc.edu/list/ucscGenomes — 组装目录。
• https://api.genome.ucsc.edu/list/tracks?genome=hg38 — 某个组装版本的轨道目录。
• https://api.genome.ucsc.edu/getData/track — 某个区间内的轨道行数据。
• https://api.genome.ucsc.edu/getData/sequence — 参考 DNA。
• 文档：https://genome.ucsc.edu/goldenPath/help/api.html

注意事项

每个坐标工具都必须指定 genome，且没有默认值。 hg19（GRCh37）和 hg38（GRCh38）是同一基因组的不同坐标系统，而且两者中的每个位置都有效——所以组装版本选错时不会报错，而是会返回看似可信、实则对应另一位点的注释。BRCA1 在 hg19 中位于 chr17:41,196,311-41,277,500，在 hg38 中则位于 chr17:43,044,295-43,170,245。约 2018 年以前的所有内容（已发表的表格、临床电子表格、大多数 dbSNP 转储）都使用 hg19。

坐标采用从 0 开始、左闭右开的形式；Genome Browser UI 使用从 1 开始、两端均包含的形式。 从浏览器位置框复制的位置，其起始位置会大 1。

染色体名称必须带 chr 前缀。 UCSC 要求使用 chr17；Ensembl/NCBI 风格的不带前缀的 17 会被拒绝。

轨道搜索会按匹配位置排序，这是有意为之。 hg38 包含约 24,000 条轨道（其中大多数是 ENCODE 子轨道），而 longLabels 是描述性文本，因此对 "gencode" 进行普通子字符串搜索会匹配 13,427 条，其中约 13,000 条是假阳性，因为 wgEncodeBroadHistone… 转为小写后会包含字面上的 "gencode"。排序会将内部名称匹配排在 shortLabel 匹配之前，再排在描述性文本匹配之前，并将驼峰命名的大小写转换处视为单词边界，从而区分 nmdEscGencode 和 wgEncode…。没有这项处理时，答案（knownGene）会排在第 2,700 页。

复合轨道会在父对象中将子轨道嵌套一层。 ucsc_tracks 会将它们展平，否则在 hg38 上搜索 "clinvar" 会漏掉 ClinVar 容器中的所有子轨道，让人误以为“UCSC 没有 ClinVar”。

getData/track 通常以轨道名称作为其行数组的键。 某些复合轨道会改用子轨道名称作为键，因此该工具包会退而使用“响应中的第一个数组”，而不是返回一个实际由名称不匹配导致的空结果。

无效的组装版本或轨道会返回 HTTP 400，并在 JSON 正文中提供有用的 error 字符串——该工具包会将其直接呈现出来，因为“hg19 不是 hg38 基因组的有效轨道”就是完整的诊断信息。

快速开始

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

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

此端点实际提供的内容

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

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

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

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

两个 URL 都会连接到同一个网关和相同的 1684+ 个数据源。唯一的区别是直接列出哪个工具包的工具；无论连接哪一个，ask_pipeworx 都能访问所有工具。

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

curl -X POST https://gateway.pipeworx.io/v1/tools/ucsc_genomes \
  -H 'Content-Type: application/json' \
  -d '{"search":"human"}'

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

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

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

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

或者直接运行它，确认服务能够启动：

npx -y @pipeworx/mcp-ucsc-genome

它通过 stdin/stdout 使用 MCP 通信，并且只会针对此工具包的工具响应 initialize/tools/list/tools/call——不包含上文网关连接额外提供的共享元工具。来源相同，工具相同，但没有 ask_pipeworx 路由功能。

使用 ask_pipeworx

你也可以用通俗易懂的语言提问，而不是直接调用工具——此功能既适用于上面的工具包端点，也适用于完整网关：

ask_pipeworx({ question: "your question about Ucsc Genome data" })

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

更多信息

• 文档和指南
• pipeworx.io

许可证

MIT