earthquake-mcp-server

<div align="center"> <h1>@cyanheads/earthquake-mcp-server</h1> <p><b>Search USGS and EMSC seismic data — real-time feeds, event queries, and earthquake counts via MCP. STDIO or Streamable HTTP.</b> <div>4 Tools • 3 Resources</div> </p> </div> <div align="center">

</div> <div align="center">

</div> <div align="center">

Public Hosted Server: https://earthquake.caseyjhand.com/mcp

</div>

---

Overview

Seismic data from USGS ComCat and the EMSC SeismicPortal. Fetch real-time earthquake feeds, search and count seismic events by time, magnitude, depth, and location, and pull full analysis detail for a single event.

Tools

| Tool | Description | |:---|:---| | earthquake_get_feed | Fetch a USGS pre-computed real-time earthquake feed by magnitude tier and time window | | earthquake_search_events | Search earthquakes by time range, magnitude, depth, location radius, PAGER alert level, or felt reports | | earthquake_count_events | Count earthquakes matching filters without fetching full records | | earthquake_get_event | Fetch one earthquake by USGS or EMSC event ID, with USGS analysis products and opt-in origins, magnitudes, phase arrivals, and aftershock forecast |

Resources

| Resource | Description | |:---|:---| | earthquake://feed/{magnitude_tier}/{time_window} | First 100-event page of a USGS real-time feed, with an exact continuation URI | | earthquake://feed/{magnitude_tier}/{time_window}/page/{cursor} | Continue the retained feed generation using the returned next_uri | | earthquake://event/{event_id} | One earthquake by USGS or EMSC event ID as injectable context, with the same detail product projection as earthquake_get_event |

Skill

| Skill | Description | |:---|:---| | earthquake-guide | Agent guide for the earthquake_* tools: identifier chains between USGS and EMSC, coverage and magnitude-scale gates, and when product and include groups answer a question. Loaded by plugin hosts from skills/ and served over MCP as skill://earthquake-guide/SKILL.md |

Capability reference

earthquake_get_feed _tool

• Choose a magnitude tier (all, 1.0, 2.5, 4.5, significant) and a window (hour, day, week, month). USGS caches these feeds; use earthquake_search_events for historical or filtered queries.
• Returns events, page count, generation time, and source feed URL. all includes microseisms; significant is USGS-curated using magnitude, felt reports, and PAGER impact.
• Each page returns limit events (default 15), fewer only on the last page. A limit above 1,000 returns 1,000 with a notice naming the requested and applied values; with EARTHQUAKE_CLAMP_LIMITS=false it is rejected instead. limit applies to the first page; later pages keep the page size in the cursor. totalCount reports the whole feed; pass nextCursor back unchanged with the same tier and window.
• Continuations read the first-read generation, unaffected by upstream edits. Retention lasts up to 15 minutes, subject to capacity eviction and restart. cursor_expired means restart without a cursor; legacy cursors must also be restarted.

---

earthquake_search_events _tool

• Search usgs or emsc by time, magnitude, depth, radius, or bounding box. A radius requires latitude, longitude, and radius_km together; box edges are independently optional, support antimeridian bounds up to ±360°, and intersect a supplied circle.
• Returns normalized events with event_type, EMSC's event_certainty, and USGS's associated_ids (other network IDs merged into the event). ignoredFilters names unsupported filters; queryEcho reports the effective query.
• Both search and count accept open magnitude_type values on either source. product_type (required product, e.g. moment-tensor) and review_status (automatic or reviewed) apply only to USGS; EMSC names them in ignoredFilters. Blank values mean omitted.
• Date-only bounds (including expanded year/year-month forms) mean midnight at the start of the named day on both sources: 2026-10-10 becomes 2026-10-10T00:00:00. Explicit time and timezone suffixes are preserved; unpadded date components are padded. Offsetless times use UTC for the 30-day default. queryEcho shows the exact effective bounds.
• Sort by time or magnitude in either direction. Each call requests limit events upstream (default 15, set by DEFAULT_LIMIT) and returns them all, fewer only on the last page. A limit above 1,000 returns 1,000 with a notice naming the requested and applied values; with EARTHQUAKE_CLAMP_LIMITS=false it is rejected instead. queryEcho.limit reports the applied limit. Continue with the returned nextOffset (offset plus the events returned, counting from 1) and the same filters, limit, and order. Search pages read the current catalog, so upstream edits can affect later pages.
• Strictly inverted magnitude, depth, or explicit time bounds fail locally as invalid_range, naming both values and recovery. Equal and single bounds remain valid; time comparisons use UTC instants, including explicit offsets. Calendar-invalid values remain for upstream rejection.
• A nonempty short page establishes totalCount; an empty first page establishes zero, while an empty later page leaves the total unknown. Full pages use a count lookup, with countUnavailable on failure. Feed, search, and event calls each share one 50-second deadline across their requests and retries; for search that includes the count lookup. Cancellation remains cancellation.

---

earthquake_count_events _tool

• Count matches using the same filters as earthquake_search_events, without fetching events. Omit start_time for the last 30 days; queryEcho reports the resolved window and applied filters.
• exceeds_limit flags the 20,000-event single-request threshold, not a retrieval ceiling: search offset paging can retrieve larger match sets. max_allowed is 20,000 for USGS and null for EMSC; ignoredFilters names filters the source cannot apply.

---

earthquake_get_event _tool

• Pass the id of any feed or search result. An EMSC unid from a source=emsc search (eight digits, underscore, seven digits, e.g. 20190706_0000043) is looked up on EMSC SeismicPortal; every other ID goes to USGS (e.g. us6000sznj).

• A USGS event returns the normalized event plus optional detail: PAGER, ShakeMap, DYFI, moment tensor, ground-failure alerts, origin quality (including depth_type, which separates an assigned depth from a located one), and finite-fault dimensions. Groups are omitted when none of their projected fields is available; absence does not imply zero impact. associated_ids lists the other network IDs USGS holds for the event; an alias such as us70004bn0 returns the preferred event (ci38457511) with the alias listed there.

• An EMSC event returns the same normalized event its search result carries, with no detail and no associated_ids.

• include opts into more for USGS events:

  | Group | Source | Extra requests | |:---|:---|:---| | origins | Every origin product in the event response, preferred first | None | | magnitudes | Event-level magnitudes from the preferred phase-data product's QuakeML, with a station count where published | One, shared with arrivals | | arrivals | Every phase arrival of that document's preferred origin, joined to its pick and sorted nearest first | One, shared with magnitudes | | aftershock_forecast | The USGS Operational Aftershock Forecast: each window's probability of an aftershock at or above each magnitude, its expected-count range, and the chance of one as large as the mainshock | One |

• A requested group that is not returned is listed in unavailable_includes: not_published when the event has no such product (every group on an EMSC event), fetch_failed when the download failed, returned HTML, did not parse, pointed outside the configured USGS origin, or answered with a redirect. The event, detail, and other groups still return; cancellation propagates. The event request and its product downloads share one 50-second deadline.

• Blank IDs fail locally; canonical IDs and aliases match case-insensitively. ShakeMap includes the producer's code_version when published.

---

earthquake://feed/{magnitude_tier}/{time_window} _resource

• Choose the same magnitude tiers and time windows as earthquake_get_feed; all 20 combinations are listed as browsable resources.
• Returns 100 events per application/json page in the compact event projection, plus totalCount, truncated, nextCursor, and next_uri. Read next_uri verbatim until it is absent. The continuation URI is earthquake://feed/{magnitude_tier}/{time_window}/page/{cursor}.
• Feed resources share retained generations with earthquake_get_feed. Cache hints are private with zero lifetime because continuation tokens belong to the requesting tenant. Upstream failures classified as ServiceUnavailable expose feed_unavailable; those classified as Timeout expose feed_timeout, each with recovery guidance and no captured upstream body. Availability failures preserve numeric HTTP status; HTTP 501 remains non-retryable and points to EMSC search. Other error classes propagate unchanged.

---

earthquake://event/{event_id} _resource

• Pass a USGS or EMSC event_id from a feed or search result. Returns the same event and optional detail products as earthquake_get_event; it takes no include.
• Uses that tool's event_deleted, not_found, source_unavailable, and source_timeout error contract.

Features

Built on @cyanheads/mcp-ts-core: stdio and Streamable HTTP transports, pluggable auth (none / jwt / oauth), swappable storage (in-memory, filesystem, Supabase, Cloudflare KV/R2/D1), structured logging with optional OpenTelemetry tracing.

USGS/