# GraceDB (pypi · gracedb-mcp)

LIGO/Virgo/KAGRA gravitational-wave alerts (GraceDB), open data (GWOSC) and GCN follow-up.

- Trust score: 82/100 (high trust)
- Change this week: +21
- Registry status: active
- Liveness: live
- Owner verified: no
- Last scored: 2026-11-04

## Components

- oci · `ghcr.io/izabelamaria24/gracedb-mcp`: 43/100, [markdown](https://verifymcp.io/servers/izabelamaria24-gracedb-mcp/ghcr-io-izabelamaria24-gracedb-mcp.md), [page](https://verifymcp.io/servers/izabelamaria24-gracedb-mcp/ghcr-io-izabelamaria24-gracedb-mcp)
- pypi · `gracedb-mcp`: 82/100 (this document), [markdown](https://verifymcp.io/servers/izabelamaria24-gracedb-mcp/gracedb-mcp.md), [page](https://verifymcp.io/servers/izabelamaria24-gracedb-mcp/gracedb-mcp)

## Channel facts

- Registry: `pypi`
- Package: `gracedb-mcp`
- Version: `0.4.0`
- Transport: `stdio`

## Trust breakdown

How this component scores in each security and reliability category. Every signal is checked automatically from public evidence about the published package, including repeated runs of it in an isolated sandbox, and we only credit what we can confirm. Scores are 0–100 per category. Scoring method: https://verifymcp.io/docs/scoring (what has changed: https://verifymcp.io/docs/scoring/changelog)

Scored 2026-11-04.

- **Supply Chain Security**: 100/100
  - No malware found by supply-chain analysis.
  - No known CVEs affecting this package version or its production dependencies.
  - Runs hatchling.build at install time, a recognised build step with no custom scripting around it.
  - 2 of 42 dependencies flagged as unhealthy.
- **Provenance & Transparency**: 97/100
  - Source repository is publicly reachable at the declared URL.
  - Cryptographically verified build provenance (signed, bound to izabelamaria24/gracedb-mcp).
  - Clear OSI-approved license (GPL-3.0-or-later).
  - Actively maintained (last published 1 days ago).
  - Disclosure check failed: no security disclosure policy was found in the source repository.
- **Schema Quality & AI Usability**: 73/100
  - 100% of prompts and resources have a non-trivial description (not blank, and not just the item's name).
  - AI-judged instruction clarity (good).
  - Context-footprint check failed: tool/resource definitions use about 3368 tokens (~224/item across 15 items; 15 tools + 0 resources), over budget; trim descriptions and params.
  - Usage-examples check failed: none of the tools include examples.
- **Stability & Change Management**: 30/100
  - Stability observed for 9 of 30 days with no destabilising changes; credit accrues until the full window elapses.
- **Tool Coverage**: 71/100
  - 100% of tools have a non-trivial description (not blank, and not just the tool's name).
  - 0% of tool parameters carry a description.
  - Structured output schemas are declared (100% of tools); any adoption earns full credit.
- **Tool Safety**: 100/100
  - No prompt-injection markers were found in the server instructions, tool names or descriptions we captured.
  - We read all 15 captured tool definition(s), and no name or description among them implies an irreversible operation.
  - An AI judge read all 15 captured unit(s) of tool text and found none that tries to manipulate the model reading it.
- **Capabilities**: 100/100
  - Implements a current MCP spec version (2026-07-28).

## Install

### How do I install the GraceDB MCP server?

GraceDB runs locally as a PyPI package, launched with uvx gracedb-mcp. Ready-made configuration for Claude, Cursor, VS Code, Codex and 5 more is on this page, copied from each client's own documentation.

### Claude

```bash
claude mcp add izabelamaria24-gracedb-mcp -- uvx gracedb-mcp
```

### Cursor

```json
{
  "mcpServers": {
    "izabelamaria24-gracedb-mcp": {
      "command": "uvx",
      "args": [
        "gracedb-mcp"
      ]
    }
  }
}
```

### VS Code

```json
{
  "servers": {
    "izabelamaria24-gracedb-mcp": {
      "command": "uvx",
      "args": [
        "gracedb-mcp"
      ]
    }
  }
}
```

### Codex

```bash
codex mcp add izabelamaria24-gracedb-mcp -- uvx gracedb-mcp
```

### opencode

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "izabelamaria24-gracedb-mcp": {
      "type": "local",
      "command": [
        "uvx",
        "gracedb-mcp"
      ],
      "enabled": true
    }
  }
}
```

### OpenClaw

```bash
openclaw mcp add izabelamaria24-gracedb-mcp --command uvx --arg gracedb-mcp
```

### Hermes

```yaml
mcp_servers:
  izabelamaria24-gracedb-mcp:
    command: "uvx"
    args: ["gracedb-mcp"]
```

### Netclaw

```json
{
  "McpServers": {
    "izabelamaria24-gracedb-mcp": {
      "Transport": "stdio",
      "Command": "uvx",
      "Arguments": [
        "gracedb-mcp"
      ]
    }
  }
}
```

### Vellum

```bash
assistant mcp add izabelamaria24-gracedb-mcp -t stdio -c uvx -a gracedb-mcp
```

### Other

```json
{
  "mcpServers": {
    "izabelamaria24-gracedb-mcp": {
      "command": "uvx",
      "args": [
        "gracedb-mcp"
      ]
    }
  }
}
```

## Changelog

Every change recorded for this component, newest first. Days that predate change tracking, or that we cannot explain, say so: "we were watching and nothing happened" and "we were not watching" are different claims.

### 2026-11-03 (score 82, +16)

- [security improvement] Malware scan: unverified → pass

### 2026-11-02 (score 66, −13)

- [security regression] Malware scan: pass → unverified
- [functional regression] Schema quality: 199 → 224
- [functional] First check of Schema quality: 100
- [functional] Package version: 0.3.0 → 0.4.0

### 2026-11-01 (score 79, +1)

No change was recorded against any check on this day. Stability & Change Management went from 17 to 20. That category is still filling its 30-day observation window: 5 days of observed history at the previous scan, 6 at this one. The score rises as the window fills, whether or not the server changes.

### 2026-10-31 (score 78, +15)

- [security improvement] Malware scan: unverified → pass

### 2026-10-30 (score 63, +2)

- [security improvement] Malware scan: unverified → pass
- [functional improvement] Stability: unverified → 0.13
- [functional] Package version: 0.2.0 → 0.3.0
- [functional] Package version: 0.2.0 → 0.2.2
- [functional] Package version: 0.2.0 → 0.2.1

### 2026-10-26 (score 61)

First indexed and scored.

## MCP tools (15)

### `search_superevents` (~286 tokens)

Search GraceDB superevents, newest first.

Args:
    start: Inclusive lower bound on creation time (ISO-8601, e.g. ``2023-05-01``
        or ``2023-05-01T00:00:00``). Optional.
    end: Inclusive upper bound on creation time (same format). Optional.
    max_far: Maximum false-alarm rate in Hz. Lower = more significant. A common
        "confident detection" threshold is ``3.2e-8`` (~1 per year). Optional.
    min_confidence: Minimum astrophysical probability in [0, 1], computed as
        ``1 - P(Terrestrial)`` from each event's p_astro file. Applied as a
        post-filter (requires extra fetches per event). Optional.
    category: ``Production`` (real alerts), ``MDC`` (simulated signals injected
        continuously, useful for testing) or ``Test``.
    max_results: Maximum number of superevents to return.

Returns:
    A dict with the resolved ``query`` string and a list of matching ``superevents``.

Input parameters:

- `category` (string)
- `end`
- `max_far`
- `max_results` (integer)
- `min_confidence`
- `start`

### `get_event_metadata` (~139 tokens)

Fetch the full record and source classification for one superevent.

Args:
    graceid: The superevent id, e.g. ``S230518h``.

Returns:
    A dict with the raw superevent record, the available file list, the
    parsed source-classification probabilities (BBH / BNS / NSBH / Terrestrial)
    when a p_astro file has been published, and ``pipelines``: each search
    pipeline's best candidate (O4 onwards), so you can see which pipelines
    found the signal and how significant each one rated it.

Input parameters:

- `graceid` (string, required)

### `download_event_files` (~164 tokens)

Download GraceDB artifacts (skymaps, p_astro, PE results, logs) for an event.

These are the files GraceDB actually hosts. This is NOT raw strain data
(use ``download_strain_data`` for that).

Args:
    graceid: The superevent id, e.g. ``S230518h``.
    filenames: Specific filenames to download. If omitted, downloads every
        file attached to the superevent.

Returns:
    A dict mapping each requested filename to the local path it was saved to,
    and ``resources`` mapping it to a ``gracedb://`` URI readable over MCP
    (files over 50 MB are local only).

Input parameters:

- `filenames`
- `graceid` (string, required)

### `get_event_labels` (~107 tokens)

GraceDB labels on a superevent, in the order they were applied, with meanings.

Labels record the event's history: data-quality checks (DQOK, DQV), human
review (ADVOK, ADVNO = retracted), injections (INJ), and which products are
ready (SKYMAP_READY, PE_READY).

Args:
    graceid: The superevent id, e.g. ``S190814bv``.

Input parameters:

- `graceid` (string, required)

### `audit_alerts` (~229 tokens)

Audit the public alerts of a period: how many, how many retracted, how fast, and by whom.

Counts all superevents created in the period, the significant public alerts
(label GCN_PRELIM_SENT) and the alerts sent only as low-significance
(LOW_SIGNIF_PRELIM_SENT, O4 onwards). Breaks the significant alerts down by
detector network, pipeline and search, and lists every retracted superevent
(ADVNO) with the hours from creation to retraction. GraceDB does not record why
an alert was retracted: read the LVK retraction circular (``search_gcn_circulars``).

Args:
    start: Start of the period (ISO-8601 date or time, UTC); matched against
        superevent creation time.
    end: End of the period, inclusive.
    category: ``Production`` (real alerts), ``MDC`` (simulated) or ``Test``.

Input parameters:

- `category` (string)
- `end` (string, required)
- `start` (string, required)

### `search_catalog_events` (~327 tokens)

Search published gravitational-wave events in the GWOSC catalogues.

Unlike GraceDB alerts, catalogue events are vetted detections with estimated
source parameters. Each event appears once, in its newest version.

Args:
    catalog: Restrict to one catalogue, e.g. ``GWTC-1-confident``,
        ``GWTC-2.1-confident``, ``GWTC-3-confident``, ``GWTC-4.0``. Omit for all.
    gps_start: Earliest event GPS time. Optional.
    gps_end: Latest event GPS time. Optional.
    min_snr: Minimum network matched-filter SNR (louder signals are clearer).
    min_p_astro: Minimum probability of astrophysical origin, 0-1.
    min_total_mass: Minimum total source-frame mass in solar masses.
    max_total_mass: Maximum total source-frame mass in solar masses.
    max_distance_mpc: Maximum luminosity distance in megaparsecs.
    max_results: Maximum number of events to return (newest first).

Returns:
    ``count`` of all matches and up to ``max_results`` event summaries with
    masses, distance, redshift, spin (chi_eff), SNR, FAR and p_astro.

Input parameters:

- `catalog`
- `gps_end`
- `gps_start`
- `max_distance_mpc`
- `max_results` (integer)
- `max_total_mass`
- `min_p_astro`
- `min_snr`
- `min_total_mass`

### `get_catalog_event` (~134 tokens)

Source parameters for one published event, with 90% credible intervals.

Args:
    name: A catalogue name such as ``GW150914`` or ``GW200129_065458``, or a
        GraceDB superevent id such as ``S190814bv`` (matched by GPS time).

Returns:
    Masses, distance, redshift, spin, SNR, FAR and p_astro as
    ``{value, interval_90}``, plus the GraceDB id, available strain files,
    parameter-estimation sets and the GWOSC event page.

Input parameters:

- `name` (string, required)

### `search_gcn_circulars` (~481 tokens)

Search NASA GCN Circulars: rapid reports from telescopes, satellites and neutrino
detectors about transients, including follow-up of gravitational-wave alerts.

Reports name gravitational-wave events by their GraceDB id (``S230518h``), so a
catalogue name such as ``GW190814`` is also searched as ``S190814bv``.

Args:
    event: An event name: GraceDB id (``S230518h``), GW name (``GW170817``), GRB
        (``GRB 230518A``), IceCube alert (``IceCube-261020A``), etc. Matches
        circulars with the name in their subject, i.e. reports about the event.
    query: Free search in Lucene syntax over ``subject``, ``body`` and ``submitter``,
        e.g. ``subject:"Fermi" AND body:"upper limit"``. Combined with ``event``
        using AND when both are given. Use ``body:"S230518h"`` to also find
        circulars that only mention an event in passing.
    start_date: Only circulars submitted on or after this date (``YYYY-MM-DD``).
    end_date: Only circulars submitted on or before this date (``YYYY-MM-DD``).
    sort: ``newest`` (default) or ``relevance`` (best for well-studied events with
        hundreds of circulars, such as GW170817).
    page: Page of results, for more than ``max_results`` matches.
    include_bodies: Include each circular's full text (about 1-3 kB each).
    max_results: Circulars per page, at most 50.

Returns:
    ``total`` matching circulars and one page of them with id, subject, event,
    submission time, links (GCN page, ADS for citation), and optionally the text;
    plus ``archive_url`` to see the same search on the GCN website.

Input parameters:

- `end_date`
- `event`
- `include_bodies` (boolean)
- `max_results` (integer)
- `page` (integer)
- `query`
- `sort` (string)
- `start_date`

### `get_gcn_circular` (~56 tokens)

Full text of one GCN Circular, with its links (GCN page, ADS for citation).

Args:
    circular_id: The circular number, e.g. ``33813``.

Input parameters:

- `circular_id` (integer, required)

### `download_strain_data` (~403 tokens)

Download public strain time series around an event from GWOSC.

IMPORTANT: GraceDB does not host raw strain. This tool reads the event GPS
time (``t_0``) from GraceDB, then fetches open strain from GWOSC. It only
succeeds for events whose data has been publicly released (past observing
runs); fresh low-latency alerts will not have public strain yet.

Requires the optional ``gwpy`` dependency (``pip install gracedb-mcp[strain]``).

Args:
    graceid: The superevent id, e.g. ``S190814bv``. When ``gps_time`` is given
        this is only used as the output folder name (e.g. ``GW150914``).
    detectors: Detector prefixes to fetch, e.g. ``["H1", "L1", "V1"]``.
        Defaults to H1 and L1.
    duration: Length of the segment in seconds, centred on ``t_0``. Up to 30 s
        fits the short file GWOSC publishes around catalogue events (the event is
        not exactly centred in it); longer windows read ~100 MB hour-long files.
    sample_rate: Target sample rate in Hz (4096 or 16384 typically).
    gps_time: Centre time in GPS seconds. Skips the GraceDB lookup, which is
        needed for O1 events such as GW150914 (``1126259462.4``) that predate
        GraceDB superevents.

Returns:
    A dict mapping each detector to the saved ``.hdf5`` strain file path, and
    ``resources`` mapping it to a ``gracedb://`` URI readable over MCP.

Input parameters:

- `detectors`
- `duration` (number)
- `gps_time`
- `graceid` (string, required)
- `sample_rate` (integer)

### `utc_to_gps` (~67 tokens)

Convert an ISO-8601 UTC timestamp to GPS seconds (handy for building queries).

Args:
    iso_timestamp: e.g. ``2015-09-14T09:50:45`` (UTC assumed if no tz given).

Input parameters:

- `iso_timestamp` (string, required)

### `check_data_availability` (~255 tokens)

Check which detectors have public GWOSC strain data for a time span.

Call this before ``download_strain_data``. Public strain exists only for
released observing runs, and detectors are often offline, so coverage is
frequently partial.

Args:
    gps_start: Start of the span in GPS seconds. Use together with ``gps_end``.
    gps_end: End of the span in GPS seconds, at most 7 days after ``gps_start``.
    event: Instead of a span, a GraceDB superevent id (``S190814bv``) or a
        catalogue name (``GW150914``); checks ``window`` seconds centred on it.
    window: Span in seconds around ``event``.
    detectors: Detectors to check. Defaults to H1, L1, V1 and K1.

Returns:
    For each detector, the public data segments and the fraction of the span
    they cover. ``available`` lists detectors with complete coverage, also
    counting the short files GWOSC publishes around catalogue events.

Input parameters:

- `detectors`
- `event`
- `gps_end`
- `gps_start`
- `window` (number)

### `list_observing_runs` (~96 tokens)

Observing runs whose data GWOSC has publicly released, oldest first.

Args:
    gps: Optional GPS time; the answer says which released run covers it, or that
        it falls outside every released run (detectors off, or data not public yet).

Returns:
    Each run's name, GPS and UTC span, detectors and dataset DOI (cite it when
    using the data).

Input parameters:

- `gps`

### `check_data_quality` (~322 tokens)

Data-quality flags for each detector over a span, from GWOSC.

Flags say whether data passes each search's vetoes: CBC (compact binaries), BURST,
CW (continuous waves) and STOCH (stochastic background), at categories CAT1 (most
basic checks) to CAT3 (strictest). ``NO_<search>_HW_INJ`` flags mark time free of
hardware injections, simulated signals physically added to the detector. CW
injections are weak, long-lasting signals present for much of each run; they matter
for continuous-wave searches, not for transients such as compact-binary mergers.

Args:
    gps_start: Start of the span in GPS seconds. Use together with ``gps_end``.
    gps_end: End of the span in GPS seconds, at most 7 days after ``gps_start``.
    event: Instead of a span, a GraceDB superevent id or catalogue name; checks
        ``window`` seconds centred on it.
    window: Span in seconds around ``event``.
    detectors: Detectors to check. Defaults to H1, L1, V1 and K1.

Returns:
    Per detector: ``data_coverage`` (fraction of the span with public data),
    ``failed`` (flags vetoing part of the time that has data), hardware
    injections in that time, and every flag's coverage.

Input parameters:

- `detectors`
- `event`
- `gps_end`
- `gps_start`
- `window` (number)

### `analyze_skymap` (~302 tokens)

Analyse a gravitational-wave sky map: how big the localisation is, how far away,
and how likely given sky positions or telescope fields are to contain the source.

Args:
    graceid: Superevent id, e.g. ``S230518h``.
    filename: Sky map to use, e.g. ``bayestar.multiorder.fits``. Defaults to the
        most recently uploaded one; later maps (Bilby, publication maps) are
        usually more accurate than the rapid BAYESTAR map.
    positions: Up to 100 sky positions (e.g. candidate host galaxies or optical
        transients) to check.
    fields: Up to 20 circular telescope fields; returns the probability inside each.

Returns:
    50% and 90% credible areas (deg^2), the overall distance estimate (Mpc), the
    most probable position, and the other available sky maps. For each position:
    the credible level (smallest credible region containing it; below 0.9 means
    inside the 90% region), probability density per deg^2 and, inside the 99%
    region, the distance along that line of sight (compare it with a galaxy's
    distance before calling it a likely host). For each field: the enclosed
    probability.

Input parameters:

- `fields`
- `filename`
- `graceid` (string, required)
- `positions`

## Diagnostics

Captured diagnostic sections: Provenance, Install scripts, Dependencies. The full working is on the page: https://verifymcp.io/servers/izabelamaria24-gracedb-mcp/gracedb-mcp#diagnostics

## Score history

- 2026-11-04: 82
- 2026-11-03: 82
- 2026-11-02: 66
- 2026-11-01: 79
- 2026-10-31: 78
- 2026-10-30: 63
- 2026-10-29: 61
- 2026-10-28: 61
- 2026-10-27: 61
- 2026-10-26: 61

## Common questions

### What is the GraceDB MCP server?

GraceDB is an MCP server listed in the public MCP registry as io.github.izabelamaria24/gracedb-mcp. LIGO/Virgo/KAGRA gravitational-wave alerts (GraceDB), open data (GWOSC) and GCN follow-up. This page covers its PyPI package (gracedb-mcp).

### Is the GraceDB MCP server safe to use?

GraceDB scores 82 out of 100 on VerifyMCP. We found no known CVEs affecting it as of 4 November 2026. Its build provenance is signed and verified. That is a record of what we were able to check automatically, not an endorsement. The category breakdown on this page shows every signal behind the number, including the ones we could not confirm.

### What tools does the GraceDB MCP server expose?

GraceDB exposes 15 tools: search_superevents, get_event_metadata, download_event_files, get_event_labels, audit_alerts, and 10 more. Their descriptions and schemas cost roughly 3,368 tokens of context every time the server is loaded.

### Is the GraceDB MCP server still maintained?

GraceDB is still listed as active in the MCP registry. We last reached this channel on 4 November 2026. Those dates come from our own scans of the registry and the channel itself, not from anything the publisher announced.

### What licence is the GraceDB MCP server under?

GraceDB declares the GPL-3.0-or-later licence, which is OSI-approved. That covers the source only, and says nothing about the cost of any service it calls.

## Links

- PyPI project: https://pypi.org/project/gracedb-mcp/
- Socket report: https://socket.dev/pypi/package/gracedb-mcp
- Repository: https://github.com/izabelamaria24/gracedb-mcp
- Changelog RSS feed: https://verifymcp.io/servers/izabelamaria24-gracedb-mcp/gracedb-mcp.xml
- Changelog JSON feed: https://verifymcp.io/servers/izabelamaria24-gracedb-mcp/gracedb-mcp.json
- HTML version of this page: https://verifymcp.io/servers/izabelamaria24-gracedb-mcp/gracedb-mcp