Skip to main content
Glama

earthquake-mcp-server

Get USGS Earthquake Feed

earthquake_get_feed
Read-onlyIdempotent

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.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
limitNoMaximum 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.
cursorNoOpaque 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.
time_windowNoTime 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.day
magnitude_tierNoMinimum 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.2.5

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
countNoNumber of events returned in this page, not the whole feed.
errorNoPresent when the call failed. Absent on success.
eventsNoEarthquake events for this page, newest first.
noticeNoRecovery guidance when the feed contains no events, or how to continue when a page was capped — narrowing the magnitude tier, widening the time window, paging with the cursor, or using earthquake_search for filtered queries. Absent when a single page covers the whole feed.
feed_urlNoSource feed URL.
truncatedNoTrue when the feed holds more events than this page returned. nextCursor carries the input for the following page.
nextCursorNoOpaque token to pass back as the cursor input for the next page. Present only when more events remain; absent means this was the last page.
totalCountNoNumber of events in the whole feed, across every page.
generated_atNoISO 8601 UTC timestamp when this feed was generated by USGS.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed14 schema fields changed
    • removedOutput schema / properties / events / items / properties / cdi / anyOf
      Removed value: -[
      -  {
      -    "type": "number"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / events / items / properties / cdi / type
      Added value: +[
      +  "number",
      +  "null"
      +]
    • removedOutput schema / properties / events / items / properties / depth_km / anyOf
      Removed value: -[
      -  {
      -    "type": "number"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / events / items / properties / depth_km / type
      Added value: +[
      +  "number",
      +  "null"
      +]
    • removedOutput schema / properties / events / items / properties / felt / anyOf
      Removed value: -[
      -  {
      -    "type": "number"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / events / items / properties / felt / type
      Added value: +[
      +  "number",
      +  "null"
      +]
    • removedOutput schema / properties / events / items / properties / magnitude / anyOf
      Removed value: -[
      -  {
      -    "type": "number"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / events / items / properties / magnitude / type
      Added value: +[
      +  "number",
      +  "null"
      +]
    • removedOutput schema / properties / events / items / properties / mmi / anyOf
      Removed value: -[
      -  {
      -    "type": "number"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / events / items / properties / mmi / type
      Added value: +[
      +  "number",
      +  "null"
      +]
    • removedOutput schema / properties / events / items / properties / significance / anyOf
      Removed value: -[
      -  {
      -    "type": "number"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / events / items / properties / significance / type
      Added value: +[
      +  "number",
      +  "null"
      +]
    • removedOutput schema / properties / events / items / properties / tsunami / anyOf
      Removed value: -[
      -  {
      -    "type": "number"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / events / items / properties / tsunami / type
      Added value: +[
      +  "number",
      +  "null"
      +]
  2. Changed6 schema fields changed
    • changedInput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
    • addedInput schema / additionalProperties
      Added value: +false
    • changedOutput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
    • addedOutput schema / anyOf
      Added value: +[
      +  {
      +    "not": {
      +      "required": [
      +        "error"
      +      ]
      +    },
      +    "required": [
      +      "count",
      +      "generated_at",
      +      "events",
      +      "feed_url"
      +    ]
      +  },
      +  {
      +    "required": [
      +      "error"
      +    ]
      +  }
      +]
    • addedOutput schema / properties / error
      Added value: +{
      +  "additionalProperties": {},
      +  "description": "Present when the call failed. Absent on success.",
      +  "properties": {
      +    "code": {
      +      "description": "JSON-RPC error code for this failure.",
      +      "maximum": 9007199254740991,
      +      "minimum": -9007199254740991,
      +      "type": "integer"
      +    },
      +    "data": {
      +      "additionalProperties": {},
      +      "properties": {
      +        "reason": {
      +          "description": "Machine-readable failure mode. Declared by this tool: `feed_unavailable`: USGS feed endpoint returns a 5xx, HTML, or is unreachable. `feed_timeout`: USGS feed endpoint did not answer before the request deadline. Other values are possible when a failure originates below the handler.",
      +          "examples": [
      +            "feed_unavailable",
      +            "feed_timeout"
      +          ],
      +          "type": "string"
      +        },
      +        "recovery": {
      +          "additionalProperties": {},
      +          "description": "Actionable next step for the caller.",
      +          "properties": {
      +            "hint": {
      +              "type": "string"
      +            }
      +          },
      +          "required": [
      +            "hint"
      +          ],
      +          "type": "object"
      +        },
      +        "retryable": {
      +          "description": "Whether retrying may succeed.",
      +          "type": "boolean"
      +        }
      +      },
      +      "type": "object"
      +    },
      +    "message": {
      +      "description": "Human-readable description of what went wrong.",
      +      "type": "string"
      +    }
      +  },
      +  "required": [
      +    "code",
      +    "message"
      +  ],
      +  "type": "object"
      +}
    • removedOutput schema / required
      Removed value: -[
      -  "count",
      -  "generated_at",
      -  "events",
      -  "feed_url"
      -]
  3. Changed2 schema fields changed
    • addedOutput schema / properties / events / items / properties / event_certainty
      Added value: +{
      +  "description": "How certain the source is of event_type: \"known\" (asserted), \"suspected\", \"unknown\", or \"unreported\". EMSC publishes this as the first character of its event-type code — a suspected explosion is not a confirmed one, and this is the only field that says so. Absent for USGS, which publishes no certainty axis, and absent for an EMSC code outside the published nomenclature.",
      +  "enum": [
      +    "known",
      +    "suspected",
      +    "unknown",
      +    "unreported"
      +  ],
      +  "type": "string"
      +}
    • changedOutput schema / properties / events / items / properties / event_type / description
      Previous value: -"Upstream event classification. USGS spells it out — \"earthquake\", \"quarry blast\", \"explosion\", \"ice quake\" — while EMSC publishes a two-letter evtype code, \"ke\" for a known earthquake and \"ue\" for an unknown event. Not every record in either catalog is a tectonic earthquake. Absent when the source publishes no classification."New value: +"What kind of event this is, in one vocabulary whichever source served it — the QuakeML type names USGS publishes (\"earthquake\", \"quarry blast\", \"explosion\", \"ice quake\"). EMSC's two-character code is decoded to the same names, so the same event carries the same value from either source; how sure the source is rides on event_certainty instead. A code outside the published nomenclature is forwarded verbatim rather than guessed at. Not every record in either catalog is a tectonic earthquake. Absent when the source publishes no classification."
  4. Changed1 schema field changed
    • addedOutput schema / properties / events / items / properties / event_type
      Added value: +{
      +  "description": "Upstream event classification. USGS spells it out — \"earthquake\", \"quarry blast\", \"explosion\", \"ice quake\" — while EMSC publishes a two-letter evtype code, \"ke\" for a known earthquake and \"ue\" for an unknown event. Not every record in either catalog is a tectonic earthquake. Absent when the source publishes no classification.",
      +  "type": "string"
      +}
  5. Changed14 schema fields changed
    • changedOutput schema / properties / events / items / properties / alert / description
      Previous value: -"PAGER estimated impact alert level. Null if not computed. USGS only."New value: +"PAGER estimated impact alert level. Null when USGS ran no PAGER assessment, and always null for EMSC, which publishes no such field."
    • addedOutput schema / properties / events / items / properties / auth
      Added value: +{
      +  "description": "Code of the agency or network the source names as authoritative for this solution, e.g. \"NEIC\", \"BMKG\", \"NDI\" from EMSC or \"us\", \"ci\", \"ak\" from USGS. Absent when the source reports none.",
      +  "type": "string"
      +}
    • changedOutput schema / properties / events / items / properties / cdi / description
      Previous value: -"Maximum reported intensity (Community Decimal Intensity, 0–12 scale). USGS only."New value: +"Maximum reported intensity (Community Decimal Intensity, 0–12 scale), derived from DYFI responses. Null when USGS computed no DYFI intensity, and always null for EMSC, which publishes no such field."
    • changedOutput schema / properties / events / items / properties / felt / description
      Previous value: -"Number of DYFI (Did You Feel It?) responses. Null if no reports. USGS only."New value: +"Number of DYFI (Did You Feel It?) responses. Null when USGS has received no reports for the event, and always null for EMSC, which publishes no DYFI field — a null is not evidence the event went unfelt."
    • changedOutput schema / properties / events / items / properties / mmi / description
      Previous value: -"Maximum ShakeMap instrumental intensity (Modified Mercalli, 0–12 scale). USGS only."New value: +"Maximum ShakeMap instrumental intensity (Modified Mercalli, 0–12 scale). Null when USGS produced no ShakeMap for the event, and always null for EMSC, which publishes no such field."
    • changedOutput schema / properties / events / items / properties / significance / description
      Previous value: -"USGS significance score (0–2000+). Combines magnitude, felt reports, PAGER. USGS only."New value: +"USGS significance score (0–2000+). Combines magnitude, felt reports, PAGER. Null when USGS computed no score, and always null for EMSC, which publishes no such field."
    • addedOutput schema / properties / events / items / properties / source_catalog
      Added value: +{
      +  "description": "Upstream catalog this solution came from, e.g. \"EMSC-RTS\" (EMSC real-time seismicity, revised as analysis continues). Absent for USGS, which publishes no catalog identifier on event records.",
      +  "type": "string"
      +}
    • addedOutput schema / properties / events / items / properties / status / anyOf
      Added value: +[
      +  {
      +    "enum": [
      +      "automatic",
      +      "reviewed",
      +      "deleted"
      +    ],
      +    "type": "string"
      +  },
      +  {
      +    "type": "null"
      +  }
      +]
    • changedOutput schema / properties / events / items / properties / status / description
      Previous value: -"Review status. Automatic detections may be revised."New value: +"Human-review state: \"automatic\" (posted by automatic processing, not yet verified by a person), \"reviewed\" (examined by an analyst), or \"deleted\". Null when the source publishes no review status — EMSC does not, so treat an EMSC solution as unverified and subject to revision rather than final."
    • removedOutput schema / properties / events / items / properties / status / enum
      Removed value: -[
      -  "automatic",
      -  "reviewed",
      -  "deleted"
      -]
    • removedOutput schema / properties / events / items / properties / status / type
      Removed value: -"string"
    • addedOutput schema / properties / events / items / properties / tsunami / anyOf
      Added value: +[
      +  {
      +    "type": "number"
      +  },
      +  {
      +    "type": "null"
      +  }
      +]
    • changedOutput schema / properties / events / items / properties / tsunami / description
      Previous value: -"1 if a tsunami warning was issued; 0 otherwise. USGS only; 0 for EMSC events."New value: +"USGS tsunami flag: 1 for large events in oceanic regions, 0 otherwise. It is not a warning — USGS states the flag does not indicate whether a tsunami did or will exist; check NOAA (tsunami.gov) for actual alert status. Null when the source publishes no such flag, as EMSC does not."
    • removedOutput schema / properties / events / items / properties / tsunami / type
      Removed value: -"number"
  6. Changed8 schema fields changed
    • addedInput schema / properties / cursor
      Added value: +{
      +  "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"
      +}
    • addedInput schema / properties / limit
      Added value: +{
      +  "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.",
      +  "maximum": 1000,
      +  "minimum": 1,
      +  "type": "integer"
      +}
    • changedOutput schema / properties / count / description
      Previous value: -"Number of events in the feed."New value: +"Number of events returned in this page, not the whole feed."
    • changedOutput schema / properties / events / description
      Previous value: -"Earthquake events, newest first."New value: +"Earthquake events for this page, newest first."
    • addedOutput schema / properties / nextCursor
      Added value: +{
      +  "description": "Opaque token to pass back as the cursor input for the next page. Present only when more events remain; absent means this was the last page.",
      +  "type": "string"
      +}
    • changedOutput schema / properties / notice / description
      Previous value: -"Recovery guidance when the feed contains no events — suggests narrowing the magnitude tier, widening the time window, or using earthquake_search for filtered queries. Absent when the feed contains events."New value: +"Recovery guidance when the feed contains no events, or how to continue when a page was capped — narrowing the magnitude tier, widening the time window, paging with the cursor, or using earthquake_search for filtered queries. Absent when a single page covers the whole feed."
    • addedOutput schema / properties / totalCount
      Added value: +{
      +  "description": "Number of events in the whole feed, across every page.",
      +  "type": "number"
      +}
    • addedOutput schema / properties / truncated
      Added value: +{
      +  "description": "True when the feed holds more events than this page returned. nextCursor carries the input for the following page.",
      +  "type": "boolean"
      +}
  7. Changed3 schema fields changed
    • addedOutput schema / properties / events / items / properties / magnitude / anyOf
      Added value: +[
      +  {
      +    "type": "number"
      +  },
      +  {
      +    "type": "null"
      +  }
      +]
    • changedOutput schema / properties / events / items / properties / magnitude / description
      Previous value: -"Preferred magnitude value."New value: +"Preferred magnitude value. Null when no magnitude was computed for the event (the title renders it as \"M ?\")."
    • removedOutput schema / properties / events / items / properties / magnitude / type
      Removed value: -"number"
  8. Changed1 schema field changed
    • addedOutput schema / properties / notice
      Added value: +{
      +  "description": "Recovery guidance when the feed contains no events — suggests narrowing the magnitude tier, widening the time window, or using earthquake_search for filtered queries. Absent when the feed contains events.",
      +  "type": "string"
      +}
  9. Changed3 schema fields changed
    • addedOutput schema / properties / events / items / properties / depth_km / anyOf
      Added value: +[
      +  {
      +    "type": "number"
      +  },
      +  {
      +    "type": "null"
      +  }
      +]
    • changedOutput schema / properties / events / items / properties / depth_km / description
      Previous value: -"Hypocenter depth in kilometers. Shallow (<70 km), intermediate (70–300 km), or deep (>300 km)."New value: +"Hypocenter depth in kilometers. Shallow (<70 km), intermediate (70–300 km), or deep (>300 km). Null for historical events where depth was not measured."
    • removedOutput schema / properties / events / items / properties / depth_km / type
      Removed value: -"number"
  10. First observed

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly/openWorld/idempotent, but the description adds substantial behavior beyond them: CDN caching at USGS, regeneration roughly once a minute, the fact that cursors are opaque and position-based (so numeric offsets would skip/repeat events), and typical result volumes per tier. This is the kind of context that changes how an agent paginates.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads purpose and the sibling contrast, then layers pagination and tier detail. Efficient overall, though the hour/month volume figures repeat the schema enum descriptions, which is mild redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a paginated, read-only feed tool, the description covers paging mechanics, cursor handling, freshness, and alternatives. With an output schema present it does not need to enumerate return fields, and it doesn't.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, but the description still adds value beyond the schema by explaining that limit applies to the first page and later pages carry page size inside the cursor, and that cursor must be passed back verbatim. The tier semantics largely restate the enum descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Fetch a USGS pre-computed real-time earthquake feed by magnitude tier and time window') and explicitly contrasts itself with the sibling earthquake_search for historical/filtered queries. An agent can distinguish this from earthquake_count, earthquake_get_event, and earthquake_search immediately.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit when-to-use guidance ('use them for what's happening now queries') and an explicit alternative with its selection condition ('For historical or filtered queries, use earthquake_search instead'). Nothing is left to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.