Gracedb MCP Server

GraceDB MCP Server

An open-source Model Context Protocol (MCP) server that exposes LIGO/Virgo/KAGRA gravitational-wave alerts from GraceDB to LLM agents. It bridges the official ligo-gracedb client with the MCP standard so an agent can query, classify, and fetch data for gravitational-wave candidate events.

Intended as the data-ingestion layer for a downstream signal-processing / anomaly-detection pipeline (e.g. isolating astrophysical "chirps" from instrumental glitches).

Tools

Resources

Every file the server downloads (up to 50 MB) is also an MCP resource, so an agent can read it without filesystem access, which is useful when the server runs in Docker or on another machine:

gracedb://files/S190814bv/p_astro.json                       (application/json)
gracedb://files/S190814bv/bayestar.png                       (image/png)
gracedb://files/GW150914/strain/H1-1126259458-8.hdf5         (application/x-hdf5)

The download tools return these URIs, clients are notified when new files appear, and files already in the data directory are listed at startup. Larger files, such as full parameter-estimation posteriors, stay on disk only.

Prompts

Ready-made workflows that chain the tools. Most clients show them as slash commands.

Skills

Agent skills cover workflows that need more than this server, such as running Python locally. They live in skills/ and are not part of the PyPI package. To use one, copy its folder to your agent's skills directory:

• Claude Code: ~/.claude/skills/
• GitHub Copilot: .github/skills/ in a project, or ~/.copilot/skills/

cp -r skills/gw-open-data-analysis ~/.claude/skills/

⚠️ Important: where strain data actually comes from

GraceDB does not host raw strain data. It stores event artifacts (skymaps, classifications, parameter-estimation results). The public strain time series lives at GWOSC and is fetched by GPS time via gwpy. Public strain is only available for released observing runs — fresh low-latency alerts will not have public strain yet. download_strain_data reflects this: it reads t_0 from GraceDB, then pulls open data from GWOSC (and cleanly reports when data isn't public).

Requirements

• Python 3.10+
• mcp, ligo-gracedb, gwosc, python-dotenv
• Optional: gwpy (for download_strain_data) — installed via the strain extra.

Install

Run straight from PyPI with uv:

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

Or from source:

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

Configuration

Copy .env.example to .env and adjust. Anonymous access is enough for public superevents:

cp .env.example .env

Run locally

gracedb-mcp          # speaks MCP JSON-RPC over stdio

Development

Requires Python 3.11+ (the mcp 2.x SDK needs 3.10+).

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

Run with Docker

A prebuilt image (linux/amd64 and arm64) is published to GHCR:

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

Or build it yourself (add --build-arg EXTRAS= for the slim variant):

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

Connect to an MCP client

Claude Desktop / VS Code (mcp.json)

Add to your MCP client configuration:

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

Or run the container directly:

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

Example agent prompts

• "Search for superevents from 2023-05-01 to 2023-06-01 with a FAR below 1e-8."
• "What's the source classification for S230518h? Is it more likely a BBH or an NSBH?"
• "Download the skymap and p_astro file for S230518h."
• "Fetch H1 and L1 strain around GW150914."
• "What are the masses of GW190814, and how certain are they?"
• "List GWTC-3 events with total mass under 10 solar masses."
• "Was S190814bv checked by a human? What do its labels mean?"
• "Is there public strain for GW190814 from every detector?"

Demo

A real session (tool results trimmed to the key fields).

You: Tell me about S190814bv. Was it real, what was it, and can I get its data?

Agent: Yes, it's real and extremely significant (false-alarm rate about 2×10⁻³³ Hz). It passed data-quality checks, a human advocate approved it, and it was never retracted. The alert called it a neutron star–black hole merger (99.8%). The final analysis (GW190814) found a 23-solar-mass black hole and a 2.6-solar-mass companion, which is too heavy for most neutron-star models and too light for known black holes, so its nature is still open. It was 230 Mpc away. Here's the sky map, and I've saved 30 s of data from both LIGO detectors and Virgo around the merger.

RL environment (experimental)

gw_rl is a Gymnasium environment built on strain fetched by this server. Each episode shows the agent a 1 s spectrogram and it answers noise, chirp or glitch (+1 correct, -1 wrong).

Real chirps are scarce, so training injects synthetic chirps into real detector noise; the real catalogue events are kept for evaluation. Chirps are IMRPhenomD waveforms from LALSimulation (--chirp imr, default) or a simple analytic sweep (--chirp toy). Glitches are real LIGO glitches labelled by Gravity Spy (--glitch real, default) or sine-Gaussian bursts (--glitch synthetic).

It is not part of the PyPI package; run it from a clone of this repository (needs 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

Roadmap

• Streamable-HTTP transport (in addition to stdio) for remote deployments.

Disclaimer

Unofficial; not affiliated with or endorsed by LIGO, Virgo, KAGRA, GraceDB or NASA GCN. Respect the GWOSC, GraceDB and GCN data-use policies.

If you publish results using data fetched by this server, cite the data sources: GWOSC (CC BY 4.0), GCN Circulars by number (each has an ADS record), and, for glitch labels, Gravity Spy.

Citing

If this server helped your work, please cite it: doi:10.5281/zenodo.23810872 (all versions; Zenodo also lists a DOI per release). GitHub's Cite this repository button (from CITATION.cff) gives APA and BibTeX.

License

GPL-3.0-or-later, matching its core dependencies ligo-gracedb and gwpy.