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			上記の共通パラメーターを参照

注： このメソッドは、バリアントに関するすべての関連付けを返します。これには、p 値がゲノム全体の有意性閾値（p ≤ 5e-8）を満たすかどうかを示す is_gwas_significant フラグも含まれます。基本的に、MCP サーバーが返すのは is_gwas_significant が True の場合のみです。

領域と形質の関連を取得する (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 を使用」と記載されたエンドポイントは、メインの REST API ではなく https://www.ebi.ac.uk/gwas/summary-statistics/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 のリストを返す場合と、レスポンス形式が想定外の場合に生の関連データ構造を返す場合があります。
• 一部のエンドポイント（特に要約統計 API を使用するもの）では、結果が 1 件のみの場合、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