Skip to content
MCP server

GraceDB

Query LIGO, Virgo and KAGRA gravitational-wave alerts, open data and GCN follow-up

Runs locallyStatus and history
Install
Pricing
Open source
Platforms
CLI, self-hosted
Runs
Locally
Version
0.4.0
Listing updated
today

Similar MCP servers

About GraceDB

GraceDB is an open-source MCP server for health and science. It runs locally on your machine and is started by your AI client.

Built as a data-ingestion layer for signal-processing work, this server wraps the official GraceDB client plus GWOSC open data and NASA's GCN Circulars. Anonymous access covers public superevents, and LVK members can authenticate with X.509 credentials. An important caveat from the README: GraceDB holds event artifacts such as sky maps, classifications and parameter-estimation results, not raw strain. Public strain comes from GWOSC and exists only for released observing runs, so fresh alerts will not have it yet.

Fifteen tools cover recent superevent searches by significance, full event metadata with BBH, BNS, NSBH or Terrestrial classification, file downloads, catalogue searches across GWTC-1 to GWTC-5, data-quality vetoes, detector data availability, observing-run lookup, sky-map analysis, and GCN Circular search. An audit_alerts tool summarises a period's alerts including retractions and how fast they came. Downloaded files up to 50 MB are exposed as MCP resources.

Four prompts chain the tools into workflows, such as an alert briefing, an event dossier written for a scientist, student or the public, and an alert-versus-catalogue comparison. An optional Claude Code skill goes further, whitening strain and matched filtering locally with Python.

Install

Run in a terminal

claude mcp add gracedb-mcp -- uvx gracedb-mcp

Add to claude_desktop_config.json

{
  "mcpServers": {
    "gracedb-mcp": {
      "command": "uvx",
      "args": [
        "gracedb-mcp"
      ]
    }
  }
}
Install in CursorOpens Cursor, which asks you to confirm. Or add it by hand:

Add to ~/.cursor/mcp.json

{
  "mcpServers": {
    "gracedb-mcp": {
      "command": "uvx",
      "args": [
        "gracedb-mcp"
      ]
    }
  }
}
Install in VS CodeOpens VS Code, which asks you to confirm. Or add it by hand:

Add to .vscode/mcp.json

{
  "servers": {
    "gracedb-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "gracedb-mcp"
      ]
    }
  }
}

Add to ~/.codeium/windsurf/mcp_config.json

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

Add to your client's MCP settings (most use this shape)

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

Using several servers? Build one config file with the MCP config generator.

Configuration

  • GRACEDB_FORCE_NOAUTHSet to true for anonymous access to public superevents.
  • GRACEDB_SERVICE_URLGraceDB API base URL (production or playground).
  • GRACEDB_MCP_DATA_DIRDirectory for downloaded files.
  • GRACEDB_FORCE_NOAUTHSet to true for anonymous access to public superevents.
  • GRACEDB_SERVICE_URLGraceDB API base URL (production or playground).

Tools this server provides (15)

Taken from the project documentation; the running server may differ.

search_superevents
Searches recent superevents by time window and significance.
get_event_metadata
Returns a full superevent record and source classification.
download_event_files
Downloads GraceDB artifacts such as skymaps and p_astro.json.
download_strain_data
Fetches public GWOSC strain around an event time.
utc_to_gps
Converts an ISO-8601 UTC timestamp to GPS seconds.
search_catalog_events
Searches published GWOSC catalogue events.
get_catalog_event
Returns source parameters for one catalogue event.
get_event_labels
Explains GraceDB labels in plain English.
audit_alerts
Summarises a period's alerts, retractions and pipelines.
check_data_availability
Shows which detectors have public strain for an event.
check_data_quality
Reports data-quality vetoes and hardware injections per detector.
list_observing_runs
Lists released observing runs and what covers a given time.
analyze_skymap
Computes credible areas and target containment probabilities.
search_gcn_circulars
Searches NASA GCN Circulars.
get_gcn_circular
Returns the full text of one GCN Circular.

What it does

Alert search
search_superevents filters recent candidates by time and false-alarm rate.
Event classification
Returns source class and labels explained in plain English.
Open strain data
Fetches public GWOSC strain for released observing runs.
Catalogue search
Searches GWTC-1 to GWTC-5 by masses, distance and SNR.
Sky map analysis
Gives credible areas and the chance that listed targets contain the source.
GCN Circulars
Searches and reads telescope and detector follow-up reports.
Workflow prompts
Alert briefing, event dossier, alert vs catalogue and alert audit.

Good for

  • Triage the last day's gravitational-wave alerts
  • Write an event summary for scientists or the public
  • Compare low-latency classifications with published masses
  • Check which detectors have open data before downloading
  • Find telescope follow-up reports for an event

Pricing

Open source

Open-source Python package

GraceDB FAQ

Do I need credentials?

Not for public superevents. Anonymous access is enough, and LVK members can add X.509 credentials.

Can it download raw strain for a fresh alert?

No. Strain lives at GWOSC and only exists for released observing runs.

How do I run it?

Use uvx --from "gracedb-mcp[strain]" gracedb-mcp, install from PyPI, or run the Docker image from GHCR.

What does it require?

Python 3.10 or later, with gwpy optional for strain download.

Is GraceDB free?

Yes. GraceDB is open source, so you can use and self-host it for free.

How do I add GraceDB to Claude Code?

Run this command in your terminal: claude mcp add gracedb-mcp -- uvx gracedb-mcp

What are the best alternatives to GraceDB?

The closest alternatives to GraceDB are Tooluniverse, Oya Browser, BasalFit, Ebi Ols and Clinicaltables.

Where this comes from

  • Description: written from the project's README.
  • Install steps: from the official MCP Registry entry.

How AIPoweredBot checks servers