GraceDB

GraceDB MCP サーバー

LLM エージェントに GraceDB の LIGO/Virgo/KAGRA 重力波アラートを公開する、オープンソースの Model Context Protocol（MCP）サーバーです。公式の ligo-gracedb クライアントを MCP 標準に接続することで、エージェントが重力波候補イベントのデータを検索、分類、取得できるようにします。

下流の信号処理／異常検出パイプライン（たとえば、機器のグリッチから天体物理学的な「チャープ」を分離する処理）のデータ取り込みレイヤーとしての利用を想定しています。

ツール

ツール	機能
search_superevents	時間範囲と有意度（FAR／天体物理学的確率）で最近のスーパーイベントを検索します。
get_event_metadata	スーパーイベントの完全な記録と発生源の分類（BBH／BNS／NSBH／Terrestrial）を取得します。
download_event_files	GraceDB の成果物（スカイマップ、p_astro.json、PE 結果、ログ）をダウンロードします。
download_strain_data	イベントの GPS 時刻付近の公開ひずみ時系列データを GWOSC から取得します。
utc_to_gps	ISO-8601 形式の UTC タイムスタンプを GPS 秒に変換します。
search_catalog_events	公開済みの GWOSC カタログイベント（GWTC-1 から GWTC-5）を、質量、距離、SNR、p_astro で検索します。
get_catalog_event	GW 名または GraceDB ID を指定して、1 件のイベントの発生源パラメーターと 90% 信頼区間を取得します。
get_event_labels	GraceDB のラベル（データ品質、レビュー、撤回、成果物の準備完了）を平易な英語で説明します。
check_data_availability	ダウンロードする前に、イベントまたは GPS 時間範囲について、どの検出器のひずみデータが GWOSC で公開されているかを確認します。

⚠️ 重要：ひずみデータの取得元

GraceDB は生のひずみデータをホストしていません。保存されているのは、イベントの成果物（スカイマップ、分類、パラメーター推定結果）です。公開ひずみ時系列データは GWOSC にあり、GPS 時刻を指定して gwpy 経由で取得します。公開ひずみデータを利用できるのは、公開済みの観測実行期間に限られます。発表されたばかりの低レイテンシーアラートでは、まだ公開ひずみデータを利用できません。download_strain_data はこの点を考慮し、GraceDB から t_0 を読み取ってから GWOSC のオープンデータを取得し、データが公開されていない場合はその旨を明確に報告します。

要件

• Python 3.10+
• mcp、ligo-gracedb、gwosc、python-dotenv
• オプション：gwpy（download_strain_data と utc_to_gps 用）。strain エクストラ経由でインストールされます。

インストール

uv を使って PyPI から直接実行します。

uvx --from "gracedb-mcp[strain]" gracedb-mcp

または、ソースから実行します。

git clone https://github.com/izabelamaria24/gracedb-mcp.git
cd gracedb-mcp
python -m venv .venv && source .venv/bin/activate
pip install -e ".[strain]"     # omit [strain] if you don't need strain download

設定

.env.example を .env にコピーして、設定を調整します。公開スーパーイベントへのアクセスには、匿名アクセスで十分です。

cp .env.example .env

変数	用途
GRACEDB_SERVICE_URL	API のベース URL（本番環境またはプレイグラウンド）。
GRACEDB_FORCE_NOAUTH	公開データへの匿名アクセスには true を指定します。
GRACEDB_PROXY / GRACEDB_CERT + GRACEDB_KEY	LVK メンバー認証（X.509）。
GRACEDB_MCP_DATA_DIR	ダウンロードしたファイルの保存先（デフォルトは ~/.cache/gracedb-mcp、Docker では /data）。

ローカルで実行

gracedb-mcp          # speaks MCP JSON-RPC over stdio

開発

Python 3.11+ が必要です（mcp 2.x SDK には 3.10+ が必要です）。

pip install -e ".[dev]"
pytest -q            # tests mock the GraceDB client, no network needed

Docker で実行

ビルド済みイメージ（linux/amd64 および arm64）を GHCR で公開しています。

docker run --rm -i -v gracedb-data:/data ghcr.io/izabelamaria24/gracedb-mcp:latest

タグ	ダウンロードサイズ	内容
latest、X.Y.Z	約 165 MB	ひずみデータのダウンロード（gwpy）を含むすべての機能。
latest-slim、X.Y.Z-slim	約 60 MB	download_strain_data と utc_to_gps 以外のすべてのツール。

または、自分でビルドします（slim バリアントでは --build-arg EXTRAS= を追加します）。

docker build -t gracedb-mcp .
docker run --rm -i -v gracedb-data:/data gracedb-mcp

MCP クライアントに接続

Claude Desktop / VS Code（mcp.json）

MCP クライアントの設定に追加します。

{
  "mcpServers": {
    "gracedb": {
      "command": "gracedb-mcp",
      "env": {
        "GRACEDB_FORCE_NOAUTH": "true",
        "GRACEDB_MCP_DATA_DIR": "./data"
      }
    }
  }
}

または、コンテナを直接実行します。

{
  "mcpServers": {
    "gracedb": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "-v", "gracedb-data:/data", "ghcr.io/izabelamaria24/gracedb-mcp:latest"]
    }
  }
}

エージェント向けプロンプトの例

• 「2023-05-01 から 2023-06-01 までの、FAR が 1e-8 未満のスーパーイベントを検索してください。」
• 「S230518h の発生源分類は何ですか？ BBH と NSBH のどちらの可能性が高いですか？」
• 「S230518h のスカイマップと p_astro ファイルをダウンロードしてください。」
• 「GW150914 の前後の H1 と L1 のひずみを取得してください。」
• 「GW190814 の質量はいくつですか？ また、どの程度確かな値ですか？」
• 「合計質量が太陽質量 10 未満の GWTC-3 イベントを一覧表示してください。」
• 「S190814bv は人間によって確認されましたか？ そのラベルは何を意味しますか？」
• 「GW190814 について、すべての検出器の公開ひずみデータがありますか？」

RL 環境（実験的）

gw_rl は、このサーバーが取得したひずみデータを基に構築された Gymnasium 環境です。各エピソードでは、エージェントに 1 秒間のスペクトログラムを提示し、ノイズ、チャープ、グリッチのいずれかで回答します（正解で +1、不正解で -1）。

実際のチャープは希少なため、トレーニングでは実際の検出器ノイズに合成チャープを注入します。実際のカタログイベントは評価用に保持されます。チャープには、LALSimulation の IMRPhenomD 波形（--chirp imr、デフォルト）または単純な解析的スイープ（--chirp toy）を使用します。グリッチには、Gravity Spy によってラベル付けされた実際の LIGO グリッチ（--glitch real、デフォルト）または正弦ガウスバースト（--glitch synthetic）を使用します。

これは PyPI パッケージには含まれていません。このリポジトリをクローンして実行してください（pip 25.1 以降が必要です）。

pip install -e . --group rl
python scripts/fetch_training_strain.py --catalog GWTC-3-confident  # small files, a few MB
python scripts/fetch_glitches.py --files 30  # ~3 GB of GWOSC hour files, cached by gwpy
python scripts/train_agent.py --algo ppo mlp cnn --verbose

ロードマップ

• リモート環境へのデプロイ向けに、stdio に加えて Streamable-HTTP トランスポートに対応します。
• キャッシュされたスカイマップと p_astro ファイル向けの MCP リソースを追加します。

免責事項

非公式のプロジェクトであり、LIGO、Virgo、KAGRA、GraceDB との提携関係や、これらからの承認はありません。GWOSC と GraceDB のデータ利用ポリシーを遵守してください。

このサーバーで取得したデータを使用して結果を公開する場合は、データソースを引用してください：GWOSC（CC BY 4.0）、およびグリッチラベルについては Gravity Spy。

ライセンス

GPL-3.0-or-later。コア依存関係である ligo-gracedb および gwpy と同じライセンスです。