# GraceDB

> GraceDB is an open-source MCP server for health and science. Query LIGO, Virgo and KAGRA gravitational-wave alerts, open data and GCN follow-up. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** CLI, self-hosted
- **Repository:** https://github.com/izabelamaria24/gracedb-mcp
- **MCP Registry name:** io.github.izabelamaria24/gracedb-mcp
- **Categories:** [health and science](https://ai-powered.com/categories/health-and-science)
- **Listing updated:** 2026-11-18

## About

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.

## Features

- **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

## Install

### Claude Code (Terminal)

```sh
claude mcp add gracedb-mcp -- uvx gracedb-mcp
```

### Claude Desktop (claude_desktop_config.json)

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

### Cursor (~/.cursor/mcp.json)

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

### VS Code (.vscode/mcp.json)

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

### Windsurf (~/.codeium/windsurf/mcp_config.json)

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

### Other clients (your client's MCP settings (most use this shape))

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

## Tools

- `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.

## 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.

## Alternatives

- [Tooluniverse](https://ai-powered.com/mcp/tooluniverse): Tooluniverse is an open-source MCP server for health and science.
- [Oya Browser](https://ai-powered.com/mcp/oya-browser): Oya Browser is a freemium MCP server for browser automation.
- [BasalFit](https://ai-powered.com/mcp/basalfit): BasalFit is a free MCP server for health and science.
- [Ebi Ols](https://ai-powered.com/mcp/ebi-ols): Ebi Ols is a freemium MCP server for health and science.
- [Clinicaltables](https://ai-powered.com/mcp/clinicaltables): Clinicaltables is a freemium MCP server for health and science.
- [Complex Portal](https://ai-powered.com/mcp/complex-portal): Complex Portal is a freemium MCP server for health and science.
- [Idigbio](https://ai-powered.com/mcp/idigbio): Idigbio is a freemium MCP server for health and science.
- [Ensembl](https://ai-powered.com/mcp/ensembl): Ensembl is a freemium MCP server for health and science.

---
Source: https://ai-powered.com/mcp/gracedb
