Genomics MCP

Genomics MCP

让 AI 助手检索真实的基因组数据和参考证据，并注明数据来源。

Genomics MCP 是一个本地的模型上下文协议服务。Agent 可以使用它查找公开数据集，并从存档文件、远程文件或本地文件中读取限定范围的数据。它还可以在公开参考数据库中查询变异和基因。区域查询使用明确指定的组装版本和从 0 开始、左闭右开的坐标。若文件格式和服务支持范围读取，则读取区域时无需下载整个文件。完整文件下载是单独执行且受预算限制的步骤。结果会报告查询过的数据来源（来源信息和各来源状态），并在来源提供相关信息时注明登录号、版本和检索时间。

这是一个研究工具，用于检索和报告数据，不提供临床解读、不调用变异，也不推断生物学结论。

阅读博客文章：Genomics MCP：面向 AI Agent 的基因组数据访问，其中包括 BCL11A 增强子的 Agent 案例研究。

适用对象

希望 Agent 从 EGA、ENA、ENCODE、GEO、NCBI 或自己的索引文件中提取数据，且无需编写集成代码的计算生物学家和研究人员。它也适合构建 Agent 或评估流程、需要真实且来源可追溯数据的人员。它本身不会生成基准测试。

示例请求

以下提示词仅供参考；结果取决于你的客户端和模型。区间采用从 0 开始、左闭右开的坐标（包含起点，不包含终点）；VCF 风格的变异位置从 1 开始。

• “显示 EGA 文件 EGAF00007243773（数据集 EGAD00001003338）中与 GRCh38 chr10:[10000, 10050) 重叠的 reads。”需要设置 GENOMICS_MCP_EGA_PUBLIC_TEST_ACCOUNT=1，这是 EGA 文档中说明的公开测试账户。
• “计算 ENCODE 文件 ENCFF792QDS 在 GRCh38 chr1:[1000000, 1001000) 上的平均信号。”
• “通过 NCBI 检查 GRCh38 变异 7-140753336-A-T 的参考碱基，然后列出其 ClinVar 记录，并分别保留胚系、体细胞和致癌性分类。”
• “下载 DQ285577.1 的 ENA FASTA，并显示前 30 个碱基。”
• “比较我的数据文件夹中两个 VCF 在 chr1:[100000, 200000) 上的基因型。”

实测示例

以上 ENCODE 请求于 2026-09-25 在全新安装环境中使用实时数据运行：

• 文件：ENCODE ENCFF792QDS，GRCh38 bigWig，1,413,106,336 字节
• 区间：chr1:[1000000, 1001000)
• 结果：通过 HTTP 范围读取获得精确均值 26.361254017233847。之后工作区占用 0 字节（没有写入磁盘，但仍发生了网络读取）。

同一安装环境还运行了另外四项实时演示：EGA 测试 BAM 区域读取、ENA 序列下载、含 ClinVar 的参考检查，以及本地 MinIO。命令和机器可读结果见：docs/demos.md。

Agent 案例研究：一个仅能使用此服务工具的 Claude Code Agent，对比了 26 个文件中 BCL11A 红系增强子的 ENCODE DNase-seq 信号，并附有文字记录和无模型重放：examples/agent-case-study/。

快速开始

容器（Linux x86_64，需 Docker）

映像适用于 linux/amd64。已在 Linux x86_64 上测试；尚未测试 macOS 上的 Docker。请先创建数据文件夹；该文件夹将以只读方式挂载。

{
  "mcpServers": {
    "genomics": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "--mount", "type=bind,source=/path/to/your/data,target=/data,readonly",
        "--mount", "type=volume,source=genomics-mcp-work,target=/work",
        "ghcr.io/rewire-bio/genomics-mcp:0.1.0"
      ]
    }
  }
}

从源代码安装（macOS arm64、Linux x86_64）

需要 Python 3.12、uv、C 编译器，以及 libcurl 和 zlib 开发文件（为支持远程文件，pyBigWig 需从源代码构建）。

git clone https://github.com/rewire-bio/genomics-mcp
cd genomics-mcp && git checkout v0.1.0
uv sync --locked --no-dev
uv run --no-dev genomics-mcp --check-config

{
  "mcpServers": {
    "genomics": {
      "command": "uv",
      "args": ["--directory", "/path/to/genomics-mcp", "run", "--no-dev", "genomics-mcp"],
      "env": { "GENOMICS_MCP_ALLOWED_ROOTS": "/path/to/your/data" }
    }
  }
}

目前还没有 PyPI 软件包。Wheel、Linux MCPB 包、固定版本的 uvx 命令、Windows（WSL2）和平台说明：docs/install.md。

覆盖范围

领域	来源和格式
发现	EGA、ENA（包括 SRA 登录号）、ENCODE、GEO、NCBI Datasets：研究、数据集、样本、按来源提供的表型、文件
基因组数据	本地磁盘、HTTPS 或 S3 上的 BAM/CRAM、VCF/BCF、FASTA、BED/GFF3/GTF、bigWig/bigBed；通过 htsget 获取 EGA 区域
传输	有预算限制、可恢复且带校验和的下载，并以本地路径返回；可选使用 SRA Toolkit 将 SRA 运行转换为 FASTQ（尚未发布）
参考	HGNC、Ensembl、ClinVar、gnomAD、UniProt、Open Targets；可选使用自己的密钥接入 AlphaGenome Atlas

全部 24 个工具和资源

分组	工具
发现	list_sources、search_datasets、describe_dataset、list_files、list_samples、get_sample_metadata
传输	fetch_file、get_transfer_status、cancel_transfer、convert_sra_run（可选，尚未发布）
基因组学	get_reads、get_coverage、get_pileup、get_variants、get_sequence、get_features、get_signal
组合分析	inspect_locus、compare_samples
参考	resolve_identifier、normalize_variant、lookup_variant、lookup_gene、lookup_protein

资源：genomics://capabilities、genomics://status、genomics://schemas、genomics://schemas/{name}。

默认设置与安全

• 限制： 区域最大为 1 Mb，记录最多 10,000 条，响应最大为 1 MiB，截止时间为 30 s；调用方可以调低这些限制。除非调用设置了更大的预算，传输大小上限为 100 MiB。发生截断时会报告。不会在不同组装版本之间进行坐标转换。

• 仅限本地： 使用 stdio，或在 127.0.0.1 上通过带 bearer token 的 Streamable HTTP。没有托管服务。本地读取仅限于你允许的文件夹，且绝不会修改源文件。

• 凭据与外联： 绝不会使用环境中的 AWS 凭据；访问私有 S3 和 EGA 需要显式配置。来自未标记为 public 的文件的值，仅当调用设置了 allow_external_annotation 时才会发送到外部 API。

• 缓存（尚未发布；仅适用于开发版检出，不包含在 v0.1.0 中）： 有界内存缓存会复用标记为 public 的公共 HTTPS 文件的字节范围（每次调用都会通过 ETag 重新验证），以及公共 API 响应。私有、签名或经过身份验证的请求绝不会使用缓存。使用 [cache] enabled = false 可关闭缓存；重启后缓存会清空。详情和测量结果：性能。

• SRA Toolkit（尚未发布；可选）： convert_sra_run 使用 NCBI 的 prefetch 和 fasterq-dump，将公共 SRR/ERR/DRR 运行转换为本地 FASTQ 文件，并作为有预算限制、可取消的任务执行。发现流程绝不会自动启动此工具。ENA FASTQ 文件无需使用此工具。安装、容器变体、限制和当前验证状态：SRA Toolkit。

配置：config.example.toml。范围和已知限制：PRD.md。目录和 PyPI 状态：发布记录。技术详情：数据访问、归档、参考数据、组合分析。安全：SECURITY.md。

开发

uv sync --locked
uv run ruff check . && uv run ruff format --check .
uv run pytest

许可证

MIT。请参阅 LICENSE。各来源的数据均受其自身条款约束。