Skip to main content
Glama
seismic-mcp

seismic-mcp

by hoon1983

seismic-mcp

A unified Model Context Protocol server for global earthquake data. Queries 20 seismic agencies in parallel; matches cross-agency reports of the same earthquake; surfaces magnitude and location discrepancies so AI agents can see what one feed alone would hide.

Status

Working:

  • 20 agencies wired up. FDSN-event: USGS, EMSC, IRIS, INGV, GeoNet, GFZ, NOA, IPGP, NCEDC, SCEDC, ISC, SED, BMKG, NIEP, RESIF, KNMI, NRCAN. Custom (non-FDSN): JMA (Japan), AFAD (Türkiye), IMO (Iceland).

  • Cross-agency reconciliation. Spatiotemporal clustering, prime-report selection (local authority > EMSC for Europe > USGS), discrepancy detection (magnitude/location/depth spread). Reviewed bulletins trump preliminary.

  • Seven MCP tools: find_events, get_event, compare_sources, find_discrepancies, list_recent_by_agency, get_agency_info, list_agencies.

  • TTL cache (60 s) with in-flight de-dup: repeated queries are sub-100 ms.

  • 57 unit tests covering parsers, matching, prime-selection, authorities, reconciliation, and cache.

  • HTTP frontend for manual inspection: form + Leaflet map + side-by-side compare drawer.

Not yet built: EMSC eventid mapping (cross-references USGS/EMSC IDs for tighter matching), populated known_aliases.json, multi-region per-event authority (KOERI alongside AFAD for Türkiye).

Related MCP server: wems-mcp-server

Safety

Reports earthquake data from multiple seismic agencies for research, journalism, situational awareness, and curiosity. It is NOT an early-warning system. All earthquake reports arrive AFTER shaking has already occurred where it was felt. For earthquake preparedness and emergency response, consult official local authorities (USGS ShakeAlert, JMA Earthquake Early Warning, etc.). Preliminary magnitudes and locations are routinely revised by reporting agencies; never make safety decisions based on a single reading.

Run

As an MCP server (Claude Desktop, VS Code, etc.)

Once published to PyPI, no checkout is needed — uvx fetches and runs it:

uvx seismic-mcp

Add to claude_desktop_config.json — Windows path is %APPDATA%\Claude\claude_desktop_config.json, macOS ~/Library/Application Support/Claude/claude_desktop_config.json:

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

To run from a local checkout instead (development):

uv sync
uv run python server.py

Restart Claude Desktop. The tools appear under the seismic-mcp server in the tools menu.

As a web frontend (manual inspection)

uv run python web.py

Then open http://127.0.0.1:8765/. Same code paths as the MCP server, just exposed over HTTP with a small UI.

Tests

uv run pytest

Architecture

server.py              FastMCP entry point — 7 @mcp.tool functions
web.py                 FastAPI HTTP wrapper around the same tools
src/
  schemas.py           Pydantic models: SourceReport, ReconciledEvent, ...
  adapters/
    base.py            SeismicAdapter protocol
    fdsn.py            Header-aware FDSN-event adapter (handles 17 networks)
    afad.py            Custom AFAD JSON adapter
    jma.py             Custom JMA list.json adapter
    imo.py             Custom IMO GeoJSON adapter
    __init__.py        Registry: make_adapter(code), supported_agencies()
  authorities.py       Regional-authority bbox lookup
  matching.py          Spatiotemporal clustering with mag-scaled thresholds
  prime_selection.py   Headline-report selection rules
  reconcile.py         Cluster → ReconciledEvent with spreads
  cache.py             TTL cache + in-flight de-dup
  tools/               One file per MCP tool
data/
  agency_metadata.json    Per-agency coverage, latency, notes
  region_authorities.json Region bboxes → authoritative agency
  known_aliases.json      (manual fallback for matching, currently {})
tests/                 pytest suite — 57 tests, fast (<1s)
static/index.html      Single-page UI for the HTTP frontend

Available Tools

7 tools
compare_sourcesA

Side-by-side per-field comparison of every agency's report for one event.

Returns a field-major view (magnitude, lat, lon, depth, time, ...) with one column per agency and the numeric spread per field. Use this when an agent needs to explain why sources disagree on a specific earthquake.

Inputs: canonical_id (required). Returns: result

find_discrepanciesA

Return events where agency reports disagree past the given thresholds.

Same query params as find_events, plus tunable spread thresholds. By default keeps only events reported by 2+ agencies, since a lone report cannot disagree with itself. Useful for journalism, QA of preliminary feeds, or surfacing where the global picture is genuinely uncertain.

Inputs: limit, agencies, end_time, radius_km, +12 more. Returns: result

find_eventsA

Find recent or historical earthquakes, reconciled across multiple seismic agencies.

Queries every supported agency in parallel (~20 networks including USGS, EMSC, JMA, INGV, GeoNet, AFAD, and others) and clusters their reports so each returned event lists every agency that picked it up — the agent sees cross-network disagreement explicitly when it exists. Unreachable agencies fail gracefully and are skipped; a 60s TTL cache makes repeat queries cheap.

Pass agencies=["USGS", "EMSC", ...] to restrict the source set. Use list_agencies to see all supported codes.

NOT for emergency or early-warning use; data is preliminary.

Defaults: last 24 hours, no magnitude filter, limit 50.

Inputs: limit, agencies, end_time, radius_km, +9 more. Returns: result

get_agency_infoA

Static metadata about a seismic agency: coverage, latency, magnitude completeness, notes.

Use to interpret cross-agency disagreement (e.g. JMA magnitudes are systematically lower than USGS Mw for the same event) or to decide which agency is authoritative for a region.

Inputs: agency (required). Returns: result

get_eventA

Fetch one reconciled event by canonical_id (format: 'AGENCY:event_id').

Re-queries the seed agency by ID, then sweeps every supported agency in parallel within ±10 minutes and ~3° of the seed to find matching reports. Returns the reconciled cluster, or None if the seed cannot be found.

Use canonical_ids from find_events (e.g. 'USGS:us6000sze1') to drill into a single event with the full cross-agency view.

Inputs: canonical_id (required). Returns: result

list_agenciesA

All agency codes this server knows about (whether FDSN-wired or not).

Inputs: no named parameters. Returns: result

list_recent_by_agencyA

Raw recent events from a single agency, without cross-agency reconciliation.

Returns SourceReport objects exactly as the agency reported them. Use this to see what one network alone is publishing (often includes small local events the global feeds miss) or to compare against the reconciled view from find_events.

Inputs: agency (required), limit, end_time, start_time, +1 more. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.4/5.0

    Scored across 7 tools

    Disambiguation5/5

    Each tool targets a distinct operation: finding reconciled events, retrieving a specific event, comparing source reports, surfacing disagreements, listing agencies, listing raw agency feeds, and fetching agency metadata. The overlap between find_events and find_discrepancies is clearly delineated by threshold filtering, and list_recent_by_agency is explicitly positioned as the raw single-agency counterpart to the reconciled find_events.

    Naming Consistency5/5

    All tools follow a snake_case verb_noun pattern: find_events, get_event, compare_sources, find_discrepancies, list_agencies, list_recent_by_agency, get_agency_info. The verbs are varied but predictable (find/list/get/compare), and the noun usage (plural for collection-style operations, singular for single-item fetches) is consistent.

    Tool Count5/5

    Seven tools is well within the ideal 3-15 range and each tool earns its place in the cross-agency seismic data domain. The count is lean enough to avoid overwhelming an agent while covering the core workflows of discovery, retrieval, comparison, and metadata lookup.

    Completeness5/5

    The domain is a read-only, cross-agency earthquake data service, and the surface is complete: discover reconciled events, fetch a specific event, compare raw source fields, find disagreement hotspots, enumerate agencies, inspect a single agency's raw feed, and understand agency-specific biases. No obvious dead ends exist—every tool's output either feeds into another tool or stands alone as a meaningful answer.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      An MCP server providing real-time access to Philippine government data including earthquakes, weather, typhoons, procurement, population, and air quality. It enables AI agents to query multiple official Philippine data sources through a unified interface for research and analysis purposes.
      41
      43 PyPI
      5
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      A powerful MCP server that connects AI assistants to authoritative natural hazard data sources, enabling monitoring of earthquakes, tsunamis, volcanoes, and solar events with configurable alerts and webhooks.
      80 PyPI
      1
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      MCP server wrapping the USGS Earthquake Hazards API, enabling AI assistants to search the global earthquake catalog, look up event details, count quakes, find 'Did You Feel It' reports, and read realtime feeds.
      5
      MIT
    • F
      license
      A
      quality
      D
      maintenance
      Exposes live earth-science data (e.g., earthquakes from USGS) as tools for MCP-compatible AI agents, enabling them to fetch and reason about real-time geophysical events.
      1
      -