io.github.cyanheads/earthquake-mcp-server

Official4 toolsLive

by cyanheads · TypeScript

Search USGS and EMSC seismic data — real-time feeds, event queries, and earthquake counts.

@cyanheads/earthquake-mcp-server (MCP)

This MCP server provides access to seismic information by searching USGS and EMSC datasets. It supports real-time feeds, event queries, and earthquake counts. Tools are exposed via MCP over either STDIO or Streamable HTTP.

🛠️ Key Features

Search USGS and EMSC seismic data
Real-time feeds
Event queries
Earthquake counts
MCP transport: STDIO or Streamable HTTP

🚀 Use Cases

Retrieve up-to-date earthquake activity from USGS/EMSC
Query events for specific earthquake information
Count earthquakes for reporting or downstream automation

⚡ Developer Benefits

Designed as an MCP server for integration with model-context workflows
Typed ecosystem indicated by TypeScript topic
Works with Bun (topic present)
Exposes 4 tools via MCP

⚠️ Limitations

Scope is limited to USGS and EMSC seismic data (as described)
Transport details are limited to STDIO and Streamable HTTP (as stated)

Topics

ai-agentbunearthquakeemscgeosciencemcpmcp-servermodel-context-protocolnatural-disasterseismictypescriptusgscyanheads

Captured live from the server via tools/list.

earthquake_get_feed

Fetch a USGS pre-computed real-time earthquake feed by magnitude tier and time window. These feeds are CDN-cached by USGS and faster and more available than the query API — use them for "what's happening now" queries. "all" includes microseisms (M<1); "significant" is a USGS curation based on magnitude, felt reports, and PAGER impact estimates. "hour" returns 0–10 events typically; "month" can exceed 10,000 for the "all" tier, so results are returned a page at a time: count is the page size, totalCount the whole feed, and nextCursor the input for the following page. The cursor is opaque and must be passed back verbatim — unlike earthquake_search, these feeds have no upstream paging parameter and USGS regenerates them about once a minute, so a numeric offset across two calls would skip or repeat events. For historical or filtered queries, use earthquake_search instead.

Parameters4

magnitude_tier	string	optional	Minimum magnitude threshold for the feed. "all" includes microseisms (M<1). "1.0" is M1.0+. "2.5" is M2.5+. "4.5" is M4.5+. "significant" is a USGS curated selection based on magnitude, felt reports, and PAGER impact estimates — not purely magnitude-based.
time_window	string	optional	Time window for the feed. "hour" typically returns 0–10 events; "month" can exceed 10,000 for the "all" tier. Prefer "hour" or "day" for real-time status checks.
limit	integer	optional	Maximum events to return in this call. Default 100, max 1000. Applies to the first page; later pages carry the page size inside the cursor, so set it on the first call rather than changing it mid-sequence.
cursor	string	optional	Opaque token for the next page, taken verbatim from a previous call's nextCursor. Omit for the first page. Do not construct, parse, or edit it — it encodes a position in the feed snapshot and is rejected if malformed.

Raw schema

{
  "type": "object",
  "properties": {
    "magnitude_tier": {
      "default": "2.5",
      "description": "Minimum magnitude threshold for the feed. \"all\" includes microseisms (M<1). \"1.0\" is M1.0+. \"2.5\" is M2.5+. \"4.5\" is M4.5+. \"significant\" is a USGS curated selection based on magnitude, felt reports, and PAGER impact estimates — not purely magnitude-based.",
      "type": "string",
      "enum": [
        "all",
        "1.0",
        "2.5",
        "4.5",
        "significant"
      ]
    },
    "time_window": {
      "default": "day",
      "description": "Time window for the feed. \"hour\" typically returns 0–10 events; \"month\" can exceed 10,000 for the \"all\" tier. Prefer \"hour\" or \"day\" for real-time status checks.",
      "type": "string",
      "enum": [
        "hour",
        "day",
        "week",
        "month"
      ]
    },
    "limit": {
      "description": "Maximum events to return in this call. Default 100, max 1000. Applies to the first page; later pages carry the page size inside the cursor, so set it on the first call rather than changing it mid-sequence.",
      "type": "integer",
      "minimum": 1,
      "maximum": 1000
    },
    "cursor": {
      "description": "Opaque token for the next page, taken verbatim from a previous call's nextCursor. Omit for the first page. Do not construct, parse, or edit it — it encodes a position in the feed snapshot and is rejected if malformed.",
      "type": "string"
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

earthquake_search

Search earthquakes by time range, magnitude, depth, location radius, PAGER alert level, or felt reports. Supports USGS (global, richer metadata: PAGER, DYFI, ShakeMap) and EMSC, an independent global catalog operated by the European-Mediterranean Seismological Centre. For location-based queries, provide latitude, longitude, and radius_km together. A rectangular study area is expressed with min_latitude, max_latitude, min_longitude, and max_longitude — each independently optional, so a single edge is a valid constraint. Combining the box with the lat/lon/radius circle intersects the two, returning only events inside both. Both catalogs include non-tectonic records (quarry blasts, explosions) — every event carries its event_type, and event_type="earthquake" filters the rest out on USGS. USGS-specific filters (alert_level, event_type, min_felt, min_significance) are not sent when source=emsc — the response names them in ignoredFilters. Use earthquake_count first to gauge result size before requesting large result sets. A single call returns at most 20,000 events; larger result sets are retrieved by paging with offset, which is passed straight through to the upstream FDSN API. When a result is capped, nextOffset carries the offset for the following page and totalCount the full match count — or countUnavailable reports that the count lookup failed and the total is unknown.

Parameters21

start_time	string	optional	Start of time range as ISO 8601 (e.g. "2026-01-01" or "2026-05-23T00:00:00"). A bare year expands to January 1st and an unpadded month or day is zero-padded, so both sources honor the same window. Defaults to 30 days before end_time (or before the current time) if omitted — applied server-side so USGS and EMSC honor the same window.
end_time	string	optional	End of time range as ISO 8601, in the same forms start_time accepts. Defaults to current time if omitted.
min_magnitude	number	optional	Minimum magnitude (Richter or equivalent). M2.5+ is felt by some people; M5+ can cause damage; M7+ is major.
max_magnitude	number	optional	Maximum magnitude.
latitude	number	optional	Latitude for radius search. Requires longitude and radius_km.
longitude	number	optional	Longitude for radius search. Requires latitude and radius_km.
radius_km	number	optional	Search radius in kilometers from the lat/lon point. 100 km covers a metro region; 500 km covers a large country. Max 20001.6, the ceiling USGS enforces. Converted to degrees for EMSC (1° ≈ 111.2 km).
min_latitude	number	optional	Southern edge of a bounding-box search, in degrees. Independent of the other three box parameters — supply any of them. Must not exceed max_latitude when both are given.
max_latitude	number	optional	Northern edge of a bounding-box search, in degrees.
min_longitude	number	optional	Western edge of a bounding-box search, in degrees. Range extends beyond ±180 so a box can cross the antimeridian (e.g. min_longitude=170, max_longitude=190) — always keep min_longitude at or below max_longitude rather than inverting the pair.
max_longitude	number	optional	Eastern edge of a bounding-box search, in degrees.
min_depth_km	number	optional	Minimum depth in kilometers. Bounded to the documented -100 to 1000 km catalog envelope. Shallow quakes (0–70 km) typically cause more surface damage than deep quakes (>300 km).
max_depth_km	number	optional	Maximum depth in kilometers. Bounded to the documented -100 to 1000 km catalog envelope.
alert_level	string	optional	Minimum PAGER alert level. PAGER estimates economic loss and casualties. "green" = minimal impact; "red" = extreme. Only available from USGS.
min_felt	integer	optional	Minimum number of DYFI (Did You Feel It?) reports. Use to find events with confirmed public impact. Only available from USGS.
min_significance	integer	optional	Minimum USGS significance score (0–2000+). Combines magnitude, felt reports, and PAGER estimates. Significant events typically score 600+. Only available from USGS.
event_type	string	optional	Filter by upstream event classification, e.g. "earthquake" to exclude quarry blasts and explosions, or "quarry blast" to see only those. Matched verbatim against the USGS catalog, which accepts any string and returns zero matches for an unrecognized one. Only available from USGS.
source	string	optional	Data source. Both catalogs are global. "usgs" covers global events with PAGER, DYFI, and ShakeMap metadata. "emsc" is an independent global catalog operated by the European-Mediterranean Seismological Centre — use it to cross-check any event, anywhere, against a separate network. It publishes no PAGER, DYFI, or ShakeMap metadata and no per-event detail endpoint; its station coverage is densest around Europe and the Mediterranean.
limit	integer	optional	Maximum events to return per call. Default 100. Large limits (>1000) may result in slow responses. Max 20000. Combine with offset to retrieve match sets larger than one call can return.
offset	integer	optional	Index of the first event to return, counting from 1 — offset=1 is the first match (both upstream APIs reject 0). Omit for the first page, then pass the nextOffset value from a capped result to fetch the next one. Ordering is set by order_by, so keep order_by, limit, and every filter identical across pages.
order_by	string	optional	Sort order. "time" returns newest first; "magnitude" returns largest first.

Raw schema

{
  "type": "object",
  "properties": {
    "start_time": {
      "description": "Start of time range as ISO 8601 (e.g. \"2026-01-01\" or \"2026-05-23T00:00:00\"). A bare year expands to January 1st and an unpadded month or day is zero-padded, so both sources honor the same window. Defaults to 30 days before end_time (or before the current time) if omitted — applied server-side so USGS and EMSC honor the same window.",
      "type": "string",
      "pattern": "^\\d{4}(-\\d{1,2}(-\\d{1,2})?)?([T ]\\d{2}:\\d{2}(:\\d{2}(\\.\\d+)?)?(Z|[+-]\\d{2}:?\\d{2})?)?$"
    },
    "end_time": {
      "description": "End of time range as ISO 8601, in the same forms start_time accepts. Defaults to current time if omitted.",
      "type": "string",
      "pattern": "^\\d{4}(-\\d{1,2}(-\\d{1,2})?)?([T ]\\d{2}:\\d{2}(:\\d{2}(\\.\\d+)?)?(Z|[+-]\\d{2}:?\\d{2})?)?$"
    },
    "min_magnitude": {
      "description": "Minimum magnitude (Richter or equivalent). M2.5+ is felt by some people; M5+ can cause damage; M7+ is major.",
      "type": "number",
      "minimum": -1,
      "maximum": 10
    },
    "max_magnitude": {
      "description": "Maximum magnitude.",
      "type": "number",
      "minimum": -1,
      "maximum": 10
    },
    "latitude": {
      "description": "Latitude for radius search. Requires longitude and radius_km.",
      "type": "number",
      "minimum": -90,
      "maximum": 90
    },
    "longitude": {
      "description": "Longitude for radius search. Requires latitude and radius_km.",
      "type": "number",
      "minimum": -180,
      "maximum": 180
    },
    "radius_km": {
      "description": "Search radius in kilometers from the lat/lon point. 100 km covers a metro region; 500 km covers a large country. Max 20001.6, the ceiling USGS enforces. Converted to degrees for EMSC (1° ≈ 111.2 km).",
      "type": "number",
      "minimum": 0,
      "maximum": 20001.6
    },
    "min_latitude": {
      "description": "Southern edge of a bounding-box search, in degrees. Independent of the other three box parameters — supply any of them. Must not exceed max_latitude when both are given.",
      "type": "number",
      "minimum": -90,
      "maximum": 90
    },
    "max_latitude": {
      "description": "Northern edge of a bounding-box search, in degrees.",
      "type": "number",
      "minimum": -90,
      "maximum": 90
    },
    "min_longitude": {
      "description": "Western edge of a bounding-box search, in degrees. Range extends beyond ±180 so a box can cross the antimeridian (e.g. min_longitude=170, max_longitude=190) — always keep min_longitude at or below max_longitude rather than inverting the pair.",
      "type": "number",
      "minimum": -360,
      "maximum": 360
    },
    "max_longitude": {
      "description": "Eastern edge of a bounding-box search, in degrees.",
      "type": "number",
      "minimum": -360,
      "maximum": 360
    },
    "min_depth_km": {
      "description": "Minimum depth in kilometers. Bounded to the documented -100 to 1000 km catalog envelope. Shallow quakes (0–70 km) typically cause more surface damage than deep quakes (>300 km).",
      "type": "number",
      "minimum": -100,
      "maximum": 1000
    },
    "max_depth_km": {
      "description": "Maximum depth in kilometers. Bounded to the documented -100 to 1000 km catalog envelope.",
      "type": "number",
      "minimum": -100,
      "maximum": 1000
    },
    "alert_level": {
      "description": "Minimum PAGER alert level. PAGER estimates economic loss and casualties. \"green\" = minimal impact; \"red\" = extreme. Only available from USGS.",
      "type": "string",
      "enum": [
        "green",
        "yellow",
        "orange",
        "red"
      ]
    },
    "min_felt": {
      "description": "Minimum number of DYFI (Did You Feel It?) reports. Use to find events with confirmed public impact. Only available from USGS.",
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991
    },
    "min_significance": {
      "description": "Minimum USGS significance score (0–2000+). Combines magnitude, felt reports, and PAGER estimates. Significant events typically score 600+. Only available from USGS.",
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    },
    "event_type": {
      "description": "Filter by upstream event classification, e.g. \"earthquake\" to exclude quarry blasts and explosions, or \"quarry blast\" to see only those. Matched verbatim against the USGS catalog, which accepts any string and returns zero matches for an unrecognized one. Only available from USGS.",
      "type": "string",
      "minLength": 1
    },
    "source": {
      "default": "usgs",
      "description": "Data source. Both catalogs are global. \"usgs\" covers global events with PAGER, DYFI, and ShakeMap metadata. \"emsc\" is an independent global catalog operated by the European-Mediterranean Seismological Centre — use it to cross-check any event, anywhere, against a separate network. It publishes no PAGER, DYFI, or ShakeMap metadata and no per-event detail endpoint; its station coverage is densest around Europe and the Mediterranean.",
      "type": "string",
      "enum": [
        "usgs",
        "emsc"
      ]
    },
    "limit": {
      "description": "Maximum events to return per call. Default 100. Large limits (>1000) may result in slow responses. Max 20000. Combine with offset to retrieve match sets larger than one call can return.",
      "type": "integer",
      "minimum": 1,
      "maximum": 20000
    },
    "offset": {
      "description": "Index of the first event to return, counting from 1 — offset=1 is the first match (both upstream APIs reject 0). Omit for the first page, then pass the nextOffset value from a capped result to fetch the next one. Ordering is set by order_by, so keep order_by, limit, and every filter identical across pages.",
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991
    },
    "order_by": {
      "default": "time",
      "description": "Sort order. \"time\" returns newest first; \"magnitude\" returns largest first.",
      "type": "string",
      "enum": [
        "time",
        "time-asc",
        "magnitude",
        "magnitude-asc"
      ]
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

earthquake_get_event

Fetch detail for a specific earthquake by USGS event ID. Returns the same normalized event a search result carries, plus a projection of the analysis products only the single-event response holds: PAGER impact alert and report link, ShakeMap peak intensity and ground motion, DYFI felt-report totals, the moment-tensor focal mechanism, landslide and liquefaction alerts, origin quality (azimuthal gap, station count, location uncertainty), and finite-fault rupture dimensions. Products are omitted when USGS produced none — a small automatic event typically has no detail at all, while a large reviewed one has most of it. Event IDs appear in the "id" field of earthquake_get_feed and earthquake_search results. This tool is USGS-only — EMSC events have no per-event detail endpoint.

Parameters1

event_id

string

required

USGS event ID, e.g. "hv74966427" or "us6000sznj". Found in the "id" field of earthquake_get_feed and earthquake_search results.

Raw schema

{
  "type": "object",
  "properties": {
    "event_id": {
      "type": "string",
      "description": "USGS event ID, e.g. \"hv74966427\" or \"us6000sznj\". Found in the \"id\" field of earthquake_get_feed and earthquake_search results."
    }
  },
  "required": [
    "event_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

earthquake_count

Count earthquakes matching filters without fetching full records. Use for statistical queries ("how many M5+ earthquakes in 2025?") or to gauge result size before calling earthquake_search. Omitting start_time counts only the last 30 days, so pass an explicit range for any period-specific question; queryEcho reports the window and filters the count actually covers. When exceeds_limit is true, the count exceeds 20,000 and a full search would be truncated — narrow filters before fetching. USGS returns the max_allowed cap (20,000); EMSC count endpoint does not return this field (max_allowed will be null). Counts can be scoped to a rectangular study area with min_latitude, max_latitude, min_longitude, and max_longitude — each independently optional. Combining the box with the lat/lon/radius circle intersects the two, counting only events inside both. Both catalogs include non-tectonic records, so a radius over a mining region counts quarry blasts alongside earthquakes — pass event_type="earthquake" on USGS to exclude them. USGS-specific filters (alert_level, event_type, min_felt, min_significance) are not sent when source=emsc — the response names them in ignoredFilters.

Parameters18

start_time	string	optional	Start of time range as ISO 8601 (e.g. "2026-01-01" or "2026-05-23T00:00:00"). A bare year expands to January 1st and an unpadded month or day is zero-padded, so both sources honor the same window. Defaults to 30 days before end_time (or before the current time) if omitted — applied server-side so USGS and EMSC honor the same window.
end_time	string	optional	End of time range as ISO 8601, in the same forms start_time accepts. Defaults to current time if omitted.
min_magnitude	number	optional	Minimum magnitude (Richter or equivalent). M2.5+ is felt by some people; M5+ can cause damage; M7+ is major.
max_magnitude	number	optional	Maximum magnitude.
latitude	number	optional	Latitude for radius search. Requires longitude and radius_km.
longitude	number	optional	Longitude for radius search. Requires latitude and radius_km.
radius_km	number	optional	Search radius in kilometers from the lat/lon point. Max 20001.6, the ceiling USGS enforces — half the Earth's great-circle circumference. Converted to degrees for EMSC (1° ≈ 111.2 km).
min_latitude	number	optional	Southern edge of a bounding-box search, in degrees. Independent of the other three box parameters — supply any of them. Must not exceed max_latitude when both are given.
max_latitude	number	optional	Northern edge of a bounding-box search, in degrees.
min_longitude	number	optional	Western edge of a bounding-box search, in degrees. Range extends beyond ±180 so a box can cross the antimeridian (e.g. min_longitude=170, max_longitude=190) — always keep min_longitude at or below max_longitude rather than inverting the pair.
max_longitude	number	optional	Eastern edge of a bounding-box search, in degrees.
min_depth_km	number	optional	Minimum depth in kilometers. Bounded to the documented -100 to 1000 km catalog envelope. Shallow quakes (0–70 km) typically cause more surface damage than deep quakes (>300 km).
max_depth_km	number	optional	Maximum depth in kilometers. Bounded to the documented -100 to 1000 km catalog envelope.
alert_level	string	optional	Minimum PAGER alert level. PAGER estimates economic loss and casualties. "green" = minimal impact; "red" = extreme. Only available from USGS.
min_felt	integer	optional	Minimum number of DYFI (Did You Feel It?) reports. Use to count events with confirmed public impact. Only available from USGS.
min_significance	integer	optional	Minimum USGS significance score (0–2000+). Combines magnitude, felt reports, and PAGER estimates. Significant events typically score 600+. Only available from USGS.
event_type	string	optional	Filter by upstream event classification, e.g. "earthquake" to exclude quarry blasts and explosions from the count, or "quarry blast" to count only those. Matched verbatim against the USGS catalog, which accepts any string and returns a count of zero for an unrecognized one. Only available from USGS.
source	string	optional	Data source. Both catalogs are global. "usgs" covers global events with PAGER, DYFI, and ShakeMap metadata. "emsc" is an independent global catalog operated by the European-Mediterranean Seismological Centre — use it to cross-check a count from a separate network. It has no PAGER, DYFI, or ShakeMap metadata; its station coverage is densest around Europe and the Mediterranean, so counts of small events differ most by region.

Raw schema

{
  "type": "object",
  "properties": {
    "start_time": {
      "description": "Start of time range as ISO 8601 (e.g. \"2026-01-01\" or \"2026-05-23T00:00:00\"). A bare year expands to January 1st and an unpadded month or day is zero-padded, so both sources honor the same window. Defaults to 30 days before end_time (or before the current time) if omitted — applied server-side so USGS and EMSC honor the same window.",
      "type": "string",
      "pattern": "^\\d{4}(-\\d{1,2}(-\\d{1,2})?)?([T ]\\d{2}:\\d{2}(:\\d{2}(\\.\\d+)?)?(Z|[+-]\\d{2}:?\\d{2})?)?$"
    },
    "end_time": {
      "description": "End of time range as ISO 8601, in the same forms start_time accepts. Defaults to current time if omitted.",
      "type": "string",
      "pattern": "^\\d{4}(-\\d{1,2}(-\\d{1,2})?)?([T ]\\d{2}:\\d{2}(:\\d{2}(\\.\\d+)?)?(Z|[+-]\\d{2}:?\\d{2})?)?$"
    },
    "min_magnitude": {
      "description": "Minimum magnitude (Richter or equivalent). M2.5+ is felt by some people; M5+ can cause damage; M7+ is major.",
      "type": "number",
      "minimum": -1,
      "maximum": 10
    },
    "max_magnitude": {
      "description": "Maximum magnitude.",
      "type": "number",
      "minimum": -1,
      "maximum": 10
    },
    "latitude": {
      "description": "Latitude for radius search. Requires longitude and radius_km.",
      "type": "number",
      "minimum": -90,
      "maximum": 90
    },
    "longitude": {
      "description": "Longitude for radius search. Requires latitude and radius_km.",
      "type": "number",
      "minimum": -180,
      "maximum": 180
    },
    "radius_km": {
      "description": "Search radius in kilometers from the lat/lon point. Max 20001.6, the ceiling USGS enforces — half the Earth's great-circle circumference. Converted to degrees for EMSC (1° ≈ 111.2 km).",
      "type": "number",
      "minimum": 0,
      "maximum": 20001.6
    },
    "min_latitude": {
      "description": "Southern edge of a bounding-box search, in degrees. Independent of the other three box parameters — supply any of them. Must not exceed max_latitude when both are given.",
      "type": "number",
      "minimum": -90,
      "maximum": 90
    },
    "max_latitude": {
      "description": "Northern edge of a bounding-box search, in degrees.",
      "type": "number",
      "minimum": -90,
      "maximum": 90
    },
    "min_longitude": {
      "description": "Western edge of a bounding-box search, in degrees. Range extends beyond ±180 so a box can cross the antimeridian (e.g. min_longitude=170, max_longitude=190) — always keep min_longitude at or below max_longitude rather than inverting the pair.",
      "type": "number",
      "minimum": -360,
      "maximum": 360
    },
    "max_longitude": {
      "description": "Eastern edge of a bounding-box search, in degrees.",
      "type": "number",
      "minimum": -360,
      "maximum": 360
    },
    "min_depth_km": {
      "description": "Minimum depth in kilometers. Bounded to the documented -100 to 1000 km catalog envelope. Shallow quakes (0–70 km) typically cause more surface damage than deep quakes (>300 km).",
      "type": "number",
      "minimum": -100,
      "maximum": 1000
    },
    "max_depth_km": {
      "description": "Maximum depth in kilometers. Bounded to the documented -100 to 1000 km catalog envelope.",
      "type": "number",
      "minimum": -100,
      "maximum": 1000
    },
    "alert_level": {
      "description": "Minimum PAGER alert level. PAGER estimates economic loss and casualties. \"green\" = minimal impact; \"red\" = extreme. Only available from USGS.",
      "type": "string",
      "enum": [
        "green",
        "yellow",
        "orange",
        "red"
      ]
    },
    "min_felt": {
      "description": "Minimum number of DYFI (Did You Feel It?) reports. Use to count events with confirmed public impact. Only available from USGS.",
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991
    },
    "min_significance": {
      "description": "Minimum USGS significance score (0–2000+). Combines magnitude, felt reports, and PAGER estimates. Significant events typically score 600+. Only available from USGS.",
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    },
    "event_type": {
      "description": "Filter by upstream event classification, e.g. \"earthquake\" to exclude quarry blasts and explosions from the count, or \"quarry blast\" to count only those. Matched verbatim against the USGS catalog, which accepts any string and returns a count of zero for an unrecognized one. Only available from USGS.",
      "type": "string",
      "minLength": 1
    },
    "source": {
      "default": "usgs",
      "description": "Data source. Both catalogs are global. \"usgs\" covers global events with PAGER, DYFI, and ShakeMap metadata. \"emsc\" is an independent global catalog operated by the European-Mediterranean Seismological Centre — use it to cross-check a count from a separate network. It has no PAGER, DYFI, or ShakeMap metadata; its station coverage is densest around Europe and the Mediterranean, so counts of small events differ most by region.",
      "type": "string",
      "enum": [
        "usgs",
        "emsc"
      ]
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

README.md15 KBView on GitHub

@cyanheads/earthquake-mcp-server

Search USGS and EMSC seismic data — real-time feeds, event queries, and earthquake counts via MCP. STDIO or Streamable HTTP.

4 Tools • 2 Resources

Version MCP SDK TypeScript Bun

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

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. Runs as a stdio process, a local Streamable HTTP server, or the public hosted endpoint above.

Tools

Tool	Description
`earthquake_get_feed`	Fetch a USGS pre-computed real-time earthquake feed by magnitude tier and time window
`earthquake_search`	Search earthquakes by time range, magnitude, depth, location radius, PAGER alert level, or felt reports
`earthquake_count`	Count earthquakes matching filters without fetching full records
`earthquake_get_event`	Fetch complete detail for a specific earthquake by USGS event ID

Resources

Resource	Description
`earthquake://feed/{magnitude_tier}/{time_window}`	USGS real-time earthquake feed as injectable context — returns the whole feed, so use the `earthquake_get_feed` tool for the broad tiers
`earthquake://event/{event_id}`	Full USGS earthquake event detail by ID as injectable context, including the same `detail` product projection as `earthquake_get_event`

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 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.
limit defaults to 100, max 1000. totalCount reports the whole feed and nextCursor retrieves another page; pass the opaque cursor back unchanged.

`earthquake_search` _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 and EMSC's event_certainty. ignoredFilters names unsupported filters; queryEcho reports the effective query.
Sort by time or magnitude in either direction. limit defaults to 100, max 20,000; paging uses a 1-based offset. Capped results carry nextOffset and totalCount, or countUnavailable if the count lookup failed. Use earthquake_count first to size the match set.

`earthquake_count` _tool

Count matches using the same filters as earthquake_search, without fetching events. Omit start_time for the last 30 days; queryEcho reports the resolved window and applied filters.
exceeds_limit flags counts above 20,000. max_allowed is 20,000 for USGS and null for EMSC; ignoredFilters names filters the source cannot apply.

`earthquake_get_event` _tool

Pass a USGS event_id from the id field of a feed or search result (e.g. us6000sznj). EMSC has no per-event detail endpoint.
Returns the normalized event plus optional detail: PAGER, ShakeMap, DYFI, moment tensor, ground-failure alerts, origin quality, and finite-fault dimensions. Groups are omitted when USGS produced no corresponding product.

`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 the whole feed as application/json, with a public 60-second cache hint. Broad week/month feeds can contain thousands of events; use earthquake_get_feed for paging.

`earthquake://event/{event_id}` _resource

Pass a USGS event_id from a feed or search result. Returns the same event and optional detail products as earthquake_get_event.
Uses that tool's 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/EMSC-specific:

Type-safe clients for the USGS FDSN/GeoJSON API and the EMSC FDSN-WS API, normalizing both into one shared earthquake domain schema
Automatic retry with backoff and per-request timeouts on every upstream call; detects USGS's rate-limited/CDN failure mode (HTML served instead of GeoJSON) and maps it to a typed service-unavailable error instead of parsing it as data
EMSC's two-character evtype code is decoded against the published event-type/certainty nomenclature into the same vocabulary USGS publishes, so event_type carries one meaning across both sources
USGS-only filters (alert_level, min_felt, min_significance, event_type) are named in ignoredFilters when source=emsc. On USGS, event_type="earthquake" excludes quarry blasts and other non-tectonic records.
No API key or rate-limit tier required — both USGS and EMSC are fully public, keyless APIs

Agent-friendly output:

Provenance — source: "usgs" | "emsc" on every response, plus source_catalog/auth fields naming the catalog and authoritative agency, so agents can weigh two independent solutions against each other
Discriminated output contracts — event_type and event_certainty travel with every event so a quarry blast or a suspected explosion is never silently read as a confirmed earthquake; exceeds_limit, countUnavailable, and truncated flags let callers branch on data instead of parsing prose
Response shaping — fields a source does not publish come back null, never a fabricated zero (tsunami, status, and mmi are always null on EMSC events); USGS-only filters dropped for an EMSC query are named in ignoredFilters rather than silently ignored
Graceful degradation — an upstream rejection surfaces the service's own explanation (offending parameter, accepted format) in the error message instead of a bare status code, and a failed follow-up count degrades to countUnavailable rather than failing the whole search

Getting started

Public Hosted Instance

A public instance is available at https://earthquake.caseyjhand.com/mcp — no installation required. Point any MCP client at it via Streamable HTTP:

json

{
  "mcpServers": {
    "earthquake-mcp-server": {
      "type": "streamable-http",
      "url": "https://earthquake.caseyjhand.com/mcp"
    }
  }
}

Self-Hosted / Local

Add the following to your MCP client configuration file.

json

{
  "mcpServers": {
    "earthquake-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/earthquake-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Or with npx (no Bun required):

json

{
  "mcpServers": {
    "earthquake-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/earthquake-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Or with Docker:

json

{
  "mcpServers": {
    "earthquake-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/earthquake-mcp-server:latest"]
    }
  }
}

For Streamable HTTP, set the transport and start the server:

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

Prerequisites

Bun v1.4.0 or higher.
No API keys required — USGS and EMSC data is fully public.

Installation

Clone the repository:

git clone https://github.com/cyanheads/earthquake-mcp-server.git

Navigate into the directory:

cd earthquake-mcp-server

Install dependencies:

bun install

Configuration

All configuration is validated at startup via Zod schemas in src/config/server-config.ts. Key environment variables:

Variable	Description	Default
`MCP_TRANSPORT_TYPE`	Transport: `stdio` or `http`	`stdio`
`MCP_HTTP_PORT`	HTTP server port	`3010`
`MCP_HTTP_ENDPOINT_PATH`	HTTP endpoint path where the MCP server is mounted	`/mcp`
`MCP_PUBLIC_URL`	Public origin override for TLS-terminating reverse-proxy deployments	none
`MCP_SESSION_MODE`	HTTP sessions: `stateful`, `stateless`, or `auto` (resolves to stateful). Overrides the `createApp()` declaration; Docker and `.env.example` also pin stateless.	`stateless` (declared in `src/index.ts`)
`MCP_AUTH_MODE`	Authentication: `none`, `jwt`, or `oauth`	`none`
`MCP_LOG_LEVEL`	Log level (`debug`, `info`, `warning`, `error`, etc.)	`info`
`MCP_GC_PRESSURE_INTERVAL_MS`	Opt-in Bun-only forced-GC pressure loop (ms). Try `60000` if heap growth is observed under sustained HTTP load.	`0` (disabled)
`LOGS_DIR`	Directory for log files on Node.js and Bun	`<project-root>/logs`
`LOG_TOOL_FAILURE_PAYLOADS`	Log failed tool arguments and results, redacted by key name. Secrets inside free-form values remain.	`false`
`LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES`	UTF-8 byte cap per logged failure payload	`16384`
`STORAGE_PROVIDER_TYPE`	Storage backend: `in-memory`, `filesystem`, `supabase`, `cloudflare-kv/r2/d1`	`in-memory`
`USGS_BASE_URL`	USGS API base URL. Override for testing or mirroring.	`https://earthquake.usgs.gov`
`EMSC_BASE_URL`	EMSC API base URL. Override for testing or mirroring.	`https://www.seismicportal.eu`
`DEFAULT_LIMIT`	Default result limit for `earthquake_search`	`100`
`REQUEST_TIMEOUT_MS`	HTTP timeout in milliseconds for upstream API calls	`10000`
`OTEL_ENABLED`	Enable OpenTelemetry	`false`
`OTEL_EXPORTER_OTLP_ENDPOINT`	Base URL for traces (`/v1/traces`) and metrics (`/v1/metrics`); signal-specific endpoint variables override it	none
`OTEL_EXPORTER_OTLP_LOGS_ENDPOINT`	Opt-in OTLP log endpoint, used as-is; the base URL never enables logs	none

Empty values and unsubstituted whole-value ${…} placeholders use the defaults. See .env.example for optional overrides.

Running the server

Local development

Build and run the production version:

# One-time build
bun run rebuild

# Run the built server
bun run start:http
# or
bun run start:stdio

Run checks and tests:

bun run devcheck  # Lints, formats, type-checks, and more
bun run test      # Runs the test suite

Docker

docker build -t earthquake-mcp-server .
docker run --rm -p 3010:3010 earthquake-mcp-server

The Dockerfile defaults to HTTP transport, stateless session mode, and logs to /var/log/earthquake-mcp-server. OpenTelemetry peer dependencies are installed by default — build with --build-arg OTEL_ENABLED=false to omit them.

Project structure

Directory	Purpose
`src/mcp-server/tools`	Tool definitions (`*.tool.ts`). Four tools across USGS and EMSC.
`src/mcp-server/resources`	Resource definitions. Feed and event resources.
`src/services/usgs`	USGS ComCat service — GeoJSON feed fetcher and FDSN query API client.
`src/services/emsc`	EMSC SeismicPortal service — FDSN event search and count endpoints.
`src/config`	Server-specific environment variable parsing and validation with Zod.
`tests/`	Unit and integration tests, mirroring the `src/` structure.

Development guide

See CLAUDE.md for development guidelines and architectural rules. The short version:

Handlers throw, framework catches — no try/catch in tool logic
Use ctx.log for logging, ctx.state for storage
Register new tools and resources in the createApp() arrays
Validate upstream data, normalize to domain types, and preserve missing values rather than inventing facts

Contributing

Issues are welcome. Run checks and tests before submitting:

bun run devcheck
bun run test

License

This project is licensed under the Apache 2.0 License. See the LICENSE file for details.

Install

Tools (4)

earthquake_get_feedearthquake_searchearthquake_get_eventearthquake_count

Configuration

Environment variables

MCP_LOG_LEVELdefault info

Sets the minimum log level for output (e.g., 'debug', 'info', 'warn').

MCP_HTTP_HOSTdefault 127.0.0.1

The hostname for the HTTP server.

MCP_HTTP_PORTdefault 3010

The port to run the HTTP server on.

MCP_HTTP_ENDPOINT_PATHdefault /mcp

The endpoint path for the MCP server.

MCP_AUTH_MODEdefault none

Authentication mode to use: 'none', 'jwt', or 'oauth'.

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "earthquake-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@cyanheads/earthquake-mcp-server@0.3.7",
        "run",
        "start:stdio"
      ],
      "env": {
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

@cyanheads/earthquake-mcp-server (MCP)

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

Topics

earthquake_get_feed

earthquake_search

earthquake_get_event

earthquake_count

@cyanheads/earthquake-mcp-server

Overview

Tools

Resources

Capability reference

earthquake_get_feed tool

earthquake_search tool

earthquake_count tool

earthquake_get_event tool

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

earthquake://event/{event_id} resource

Features

Getting started

Public Hosted Instance

Self-Hosted / Local

Prerequisites

Installation

Configuration

Running the server

Local development

Docker

Project structure

Development guide

Contributing

License

Install

Configuration

Related servers

`earthquake_get_feed` _tool

`earthquake_search` _tool

`earthquake_count` _tool

`earthquake_get_event` _tool

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

`earthquake://event/{event_id}` _resource