GWAS Catalog MCP Server

GWAS Catalog MCP 服务

概述

此 MCP 服务提供了 GWAS Catalog REST API 的编程接口，可访问 GWAS 研究、变异、性状和关联数据。该服务会自动处理大型结果集，同时提供内存结果和基于文件的存储选项。

状态

🚧 正在积极开发中 🚧

此项目目前正在积极开发中。功能和 API 可能会随时更改，恕不另行通知。

依赖项

• uv
• mcp[cli]
• fastmcp
• requests

目录结构

.
├── server.py             # Main FastMCP server entrypoint
├── utils.py              # Utility functions
├── pyproject.toml        # Project metadata and dependencies
├── README.md             # Usage and documentation
├── tests/                # Test suite and test data
│   ├── run_tests.py
│   ├── input/
│   └── output/
│       ├── success/
│       └── error/
└── ...

设置和运行

安装依赖项

uv sync

激活虚拟环境

. .venv/bin/activate

运行 MCP 服务

uv run server.py

运行测试

python tests/run_tests.py

MCP 工具规范

工具名称

• GWAS_catalog

通用参数

大多数工具支持以下通用参数：

参数	类型	默认值	说明
max_items_in_memory	int	5000	在内存中返回的最大项目数
force_to_file	bool	False	无论结果大小如何，都强制将结果写入文件
output_dir	str	"/tmp"	结果超过限制时用于输出文件的目录
force_no_file	bool	False	绝不将结果写入文件
remove_links	bool	True	从 API 响应中移除 '_links' 字段

工具端点和参数

获取研究

参数	类型	必填	说明	示例
studyId	str	是	GWAS Catalog 研究标识符	"GCST000001"
remove_links	bool	否	移除 '_links' 字段（默认值：True）

获取关联

参数	类型	必填	说明	示例
associationId	str	是	GWAS Catalog 关联标识符	"123456"
remove_links	bool	否	移除 '_links' 字段（默认值：True）

获取变异

参数	类型	必填	说明	示例
variantId	str	是	变异标识符（例如，rsID）	"rs123"
remove_links	bool	否	移除 '_links' 字段（默认值：True）

获取性状

参数	类型	必填	说明	示例
efoId	str	是	EFO 性状标识符	"EFO_0000305"
remove_links	bool	否	移除 '_links' 字段（默认值：True）

在区域中搜索变异

参数	类型	必填	描述	示例
chromosome	str	是	染色体（例如，"1"）	"1"
start	int	是	起始位置（GRCh38/hg38）	1000000
end	int	是	结束位置（GRCh38/hg38）	2000000
efo_id	str	否	EFO 性状标识符	"EFO_0008531"
...common			请参阅上方的通用参数

根据 EFO ID 获取变异

参数	类型	必填	描述	示例
efo_ids	list	是	EFO 性状标识符列表	["EFO_0000305", "EFO_0000310"]
...common			请参阅上方的通用参数

性状变异排名

参数	类型	必填	描述	示例
efo_id	str	是	EFO 性状标识符	"EFO_0008531"
top_n	int	否	返回的排名靠前记录数（默认值：10）	10
...common			请参阅上方的通用参数

获取研究关联

参数	类型	必填	描述	示例
studyId	str	是	GWAS Catalog 研究标识符	"GCST000001"
...common			请参阅上方的通用参数

获取性状研究

参数	类型	必填	描述	示例
efoId	str	是	EFO 性状标识符	"EFO_0000305"
...common			请参阅上方的通用参数

获取性状关联

参数	类型	必填	描述	示例
efoId	str	是	EFO 性状标识符	"EFO_0000305"
...common			请参阅上方的通用参数

根据变异获取关联 （使用 GWAS Catalog REST API）

参数	类型	必填	描述	示例
variantId	str	是	变异标识符	"rs112735431"
...common			请参阅上方的通用参数

注意： 此方法会返回某个变异的所有关联，其中包括 is_gwas_significant 标志，用于指示 p 值是否达到全基因组显著性阈值（p ≤ 5e-8）。基本上，只有当 is_gwas_significant 为 True 时，MCP 服务才会返回结果。

获取区域-性状关联 (使用 GWAS Summary Statistics API)

参数	类型	必填	描述	示例
chromosome	str	是	染色体（例如 "1"）	"1"
start	int	是	起始位置（碱基对）	1000000
end	int	是	结束位置（碱基对）	2000000
efo_id	str	是	EFO 性状标识符	"EFO_0008531"
...common			参见上文的通用参数

注意： 标记为“使用 GWAS Summary Statistics API”的端点会访问 https://www.ebi.ac.uk/gwas/summary-statistics/api，而非主 REST API。

输出格式

所有 API 响应均遵循一致的结构：

{
  "request_url": "https://www.ebi.ac.uk/gwas/rest/api/...",
  "items": [...],  // List of results, limited by max_items_in_memory
  "total_items_aft_process": 123,  // Total number of results after processing
  "is_complete": true,  // Whether all results are included in items
  "metadata": {
    "subset_size": 100,  // Number of items in the current response (after using max_items_in_memory parameter)
    "max_items_in_memory": 5000,  // Current memory threshold
    "total_items": 150,  // Total number of items before processing
    "significant_items": 80  // Number of genome-wide significant items (if applicable)
  }
}

大型结果集

当结果超过 max_items_in_memory 时：

1. 部分结果会在 items 字段中返回
2. is_complete 将为 False
3. 完整数据集会自动保存到文件
4. 响应中会包含带有文件路径的 output_file 字段

大型结果响应示例：

{
  "request_url": "...",
  "items": [...],  // First max_items_in_memory results
  "total_items_aft_process": 10000,
  "is_complete": false,
  "metadata": {
    "subset_size": 5000,
    "max_items_in_memory": 5000,
    "total_items": 12000,  // Original number of items
    "significant_items": 8000,  // Number of genome-wide significant items
    "output_file": "/tmp/large_result_abc123.json"
  }
}

重要提示：

• 始终检查 is_complete 和 output_file 字段。如果 is_complete 为 false，则 items 中仅包含部分结果，完整结果已保存到 output_file 指定的文件中。
• 对于处理 p 值的端点（例如关联），total_items 表示原始数量，而 total_items_aft_process 表示筛选后的数量。
• 与研究相关的端点不包含 p 值相关元数据（significant_items）。

特殊输出说明

• get_trait_associations 可能返回关联 ID 列表；如果响应格式不符合预期，则会返回原始关联数据结构。
• 某些端点（尤其是使用 summary-statistics API 的端点）在只找到一个结果时，可能会在 items 中返回单个对象。

致谢

此工具依赖 GWAS Catalog REST API 和 GWAS Summary Statistics API。

在工作中使用此工具时，请引用并致谢 GWAS Catalog 及各项研究。

许可证

此 MCP 服务本身采用 Apache License 2.0 许可，详情请参阅 LICENSE 文件。

本项目使用 GWAS Catalog REST API 以及 EMBL-EBI 提供的数据。使用此工具或其输出时，请确保引用 GWAS Catalog 和原始研究。详情请参阅 GWAS Catalog 使用条款。

致谢

• GWAS Catalog
• FastMCP