@cyanheads/earthquake-mcp-server

v0.1.9 pre-1.0

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

public 4 tools 2 resources protocol 2025-11-25 github cyanheads/earthquake-mcp-server

claude mcp add --transport http earthquake-mcp-server https://earthquake.caseyjhand.com/mcp

codex mcp add earthquake-mcp-server --url https://earthquake.caseyjhand.com/mcp

{
  "mcpServers": {
    "earthquake-mcp-server": {
      "url": "https://earthquake.caseyjhand.com/mcp"
    }
  }
}

gemini mcp add --transport http earthquake-mcp-server https://earthquake.caseyjhand.com/mcp

{
  "mcpServers": {
    "earthquake-mcp-server": {
      "command": "bunx",
      "args": [
        "@cyanheads/earthquake-mcp-server@latest"
      ]
    }
  }
}

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

curl -X POST https://earthquake.caseyjhand.com/mcp \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"curl","version":"1.0.0"}}}'

Built on@cyanheads/mcp-ts-core v0.9.13

Tools

earthquake_get_feed

open-world

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. For historical or filtered queries, use earthquake_search instead.

read

invocation

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "earthquake_get_feed",
    "arguments": {}
  }
}

schema

{
  "$schema": "https://json-schema.org/draft/2020-12/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"
      ]
    }
  },
  "required": [
    "magnitude_tier",
    "time_window"
  ],
  "additionalProperties": false
}

view source ↗

earthquake_search

open-world

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 (European-Mediterranean, independent catalog). For location-based queries, provide latitude, longitude, and radius_km together. USGS-specific filters (alert_level, min_felt, min_significance) are ignored when source=emsc. Use earthquake_count first to gauge result size before requesting large result sets. Results are capped at 20,000 events per query.

read

invocation

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "earthquake_search",
    "arguments": {}
  }
}

schema

{
  "$schema": "https://json-schema.org/draft/2020-12/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\"). Defaults to 30 days before end_time if omitted.",
      "type": "string"
    },
    "end_time": {
      "description": "End of time range as ISO 8601. Defaults to current time if omitted.",
      "type": "string"
    },
    "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. Converted to degrees for EMSC (1° ≈ 111.2 km).",
      "type": "number",
      "minimum": 0,
      "maximum": 20002
    },
    "min_depth_km": {
      "description": "Minimum depth in kilometers. Shallow quakes (0–70 km) typically cause more surface damage than deep quakes (>300 km).",
      "type": "number"
    },
    "max_depth_km": {
      "description": "Maximum depth in kilometers.",
      "type": "number"
    },
    "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
    },
    "source": {
      "default": "usgs",
      "description": "Data source. \"usgs\" covers global events with PAGER, DYFI, and ShakeMap metadata. \"emsc\" covers the European-Mediterranean region with an independent catalog — useful for cross-verification or European-focused queries.",
      "type": "string",
      "enum": [
        "usgs",
        "emsc"
      ]
    },
    "limit": {
      "description": "Maximum events to return. Default 100. Large limits (>1000) may result in slow responses. Max 20000.",
      "type": "integer",
      "minimum": 1,
      "maximum": 20000
    },
    "order_by": {
      "default": "time",
      "description": "Sort order. \"time\" returns newest first; \"magnitude\" returns largest first.",
      "type": "string",
      "enum": [
        "time",
        "time-asc",
        "magnitude",
        "magnitude-asc"
      ]
    }
  },
  "required": [
    "source",
    "order_by"
  ],
  "additionalProperties": false
}

view source ↗

earthquake_get_event

open-world

Fetch detail for a specific earthquake by USGS event ID. Returns felt reports count (DYFI), ShakeMap maximum intensity (MMI), PAGER alert level, tsunami flag, and magnitude type. 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.

read

invocation

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "earthquake_get_event",
    "arguments": {
      "event_id": "<event_id>"
    }
  }
}

schema

{
  "$schema": "https://json-schema.org/draft/2020-12/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"
  ],
  "additionalProperties": false
}

view source ↗

earthquake_count

open-world

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. 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). USGS-specific filters (alert_level, min_felt, min_significance) are ignored when source=emsc.

read

invocation

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "earthquake_count",
    "arguments": {}
  }
}

schema

{
  "$schema": "https://json-schema.org/draft/2020-12/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\"). Defaults to 30 days before end_time if omitted.",
      "type": "string"
    },
    "end_time": {
      "description": "End of time range as ISO 8601. Defaults to current time if omitted.",
      "type": "string"
    },
    "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. Converted to degrees for EMSC (1° ≈ 111.2 km).",
      "type": "number",
      "minimum": 0,
      "maximum": 20002
    },
    "min_depth_km": {
      "description": "Minimum depth in kilometers. Shallow quakes (0–70 km) typically cause more surface damage than deep quakes (>300 km).",
      "type": "number"
    },
    "max_depth_km": {
      "description": "Maximum depth in kilometers.",
      "type": "number"
    },
    "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
    },
    "source": {
      "default": "usgs",
      "description": "Data source. \"usgs\" covers global events with PAGER, DYFI, and ShakeMap metadata. \"emsc\" covers the European-Mediterranean region.",
      "type": "string",
      "enum": [
        "usgs",
        "emsc"
      ]
    }
  },
  "required": [
    "source"
  ],
  "additionalProperties": false
}

view source ↗

Resources

earthquake-feed

Direct access to a USGS real-time earthquake feed as injectable context. magnitude_tier: all | 1.0 | 2.5 | 4.5 | significant. time_window: hour | day | week | month.

uri earthquake://feed/{magnitude_tier}/{time_window} mime application/json

earthquake-event

Earthquake event detail by USGS event ID as injectable context. Returns felt reports, ShakeMap intensity, PAGER alert, tsunami flag, and magnitude type. Use event IDs from earthquake_get_feed or earthquake_search results.

uri earthquake://event/{event_id} mime application/json