Skip to main content
Glama
enesjakozh
blake365

Claude MCP Server for USGS Quakes API

by blake365
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Local

usgs-quakes-mcp

MCP server for the USGS earthquake catalog

npm version

An MCP server providing access to the USGS FDSN event API from Claude Desktop, Claude Code, and any other MCP client.

npx -y usgs-quakes-mcp

No API key required — the USGS service is free and public.

Overview

This Model Context Protocol (MCP) server enables AI assistants and applications to:

  • Get earthquake data through a wide variety of search parameters

  • Get details about a specific earthquake

Users can run queries using natural language.

Related MCP server: quake-mcp

Sample Output

Q: find earthquakes over 2 magnitude in florida over the last 20 years

A: I'll help you search for earthquakes in Florida with a magnitude greater than 2.0 over the past 20 years.

View Result from find-earthquakes from usgs-quakes (local)

{
  "endTime": "2024-12-28T23:59:59",
  "startTime": "2004-12-28T00:00:00",
  "maxLatitude": 31.000888,
  "minLatitude": 24.396308,
  "maxLongitude": -80.031362,
  "minLongitude": -87.634896,
  "minmagnitude": 2
}

Based on the USGS earthquake data, there have been three notable earthquakes in or near Florida over the past 20 years:

  1. A magnitude 5.9 earthquake in the Gulf of Mexico on September 10, 2006 Located offshore at coordinates 26.319°N, 86.606°W Depth: 14 km This was the largest earthquake in the region during this period It was widely felt, with 5,763 people reporting feeling the quake

  2. A magnitude 2.8 earthquake near Jay, Florida on March 6, 2019 Located at coordinates 30.9718°N, 87.1719°W Depth: 5 km 49 people reported feeling this earthquake

  3. A magnitude 2.7 earthquake near Century, Florida on March 24, 2019 Located at coordinates 30.9622°N, 87.2384°W Depth: 5 km 4 people reported feeling this earthquake

It's worth noting that Florida experiences relatively few earthquakes compared to more seismically active regions of the United States. The two 2019 earthquakes occurred in the Florida panhandle, while the larger 2006 event was offshore in the Gulf of Mexico.

Q: get the details of the Jay Florida earthquake

A: I'll get the detailed information about the magnitude 2.8 earthquake that occurred near Jay, Florida.

View Result from find-earthquake-details from usgs-quakes (local)

{
  "eventid": "us1000jbw4"
}

Here are the key details about the Jay, Florida earthquake: Date and Time: March 7, 2019, at 04:45:52 UTC Location: 2 km (1.2 miles) Northwest of Jay, Florida Coordinates: 30.9718°N, 87.1719°W Depth: 5 kilometers (3.1 miles) Magnitude: 2.8 mb_lg (body wave magnitude)

Additional details:

  • 49 people reported feeling the earthquake

  • The Community Internet Intensity Map (CIIM) showed a maximum intensity of 2.7

  • There was no tsunami generated

  • The earthquake was reviewed and confirmed by USGS scientists

  • The location had a horizontal error margin of about 6.2 km

  • The magnitude calculation used data from 11 seismic stations

  • The earthquake was also detected by the New Mexico seismic network (NM), which calculated a slightly different magnitude of 2.63

Technical measurements:

  • Azimuthal gap: 243 degrees (indicates moderate coverage by seismic stations)

  • RMS error: 0.59 (indicates reasonable quality of the location estimate)

  • Minimum distance to nearest station: 0.222 degrees

  • Standard error for magnitude: 0.154

This was a relatively minor earthquake, but notable for Florida which rarely experiences seismic activity. The fact that it was felt by 49 people suggests it was noticeable to residents in the immediate area, though no significant damage would be expected from an earthquake of this magnitude.

Installation

Requires Node.js 20 or newer. No install step is needed — npx fetches the server on first run.

Claude Desktop

  1. Open your Claude Desktop configuration at:

    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

    • Windows: %APPDATA%\Claude\claude_desktop_config.json

  2. Add the server configuration:

{
    "mcpServers": {
        "usgs-quakes": {
            "command": "npx",
            "args": ["-y", "usgs-quakes-mcp"]
        }
    }
}

  1. Close/Quit then restart Claude Desktop

Claude Code

claude mcp add usgs-quakes -- npx -y usgs-quakes-mcp

Any other MCP client

The server speaks MCP over STDIO. Run it with npx -y usgs-quakes-mcp, or install it globally with npm install -g usgs-quakes-mcp and run usgs-quakes-mcp.

Tools

  • find-earthquakes — search by time, bounding box, radius, magnitude, and depth

  • count-earthquakes — count matches without returning events, to size a query first

  • find-earthquake-details — full detail for one event id, including origin quality metrics

Data source

Data comes from the USGS FDSN event web service. The service caps any single query at 20,000 events.

Development

npm install        # install dependencies
npm run dev        # run from source over STDIO, no build step
npm run build      # compile TypeScript to build/
npm run typecheck  # type-check without emitting

src/server.ts holds all the tools and API calls — that is the file to edit. src/index.ts is just the STDIO entry point.

To point Claude Desktop at a local build instead of the published package, use "command": "node" with "args": ["/full/path/to/usgs-quakes/build/index.js"], and restart Claude Desktop after each rebuild.

Troubleshooting

If Claude Desktop cannot find npx, provide its full path (on macOS, typically /usr/local/bin/npx or /opt/homebrew/bin/npx). The same applies to node if you are running a local build.

Available Tools

3 tools
count-earthquakesCount EarthquakesA
Read-only

Count earthquakes matching the given search parameters, without returning the events themselves. Useful for sizing a query before running it.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoMaximum number of events to return (service maximum 20000)
endTimeNoLimit to events on or before this end time. Times use ISO8601 Date/Time format. Unless a timezone is specified, UTC is assumed. Defaults to NOW.
orderbyNoSort order. Defaults to time, most recent first.
latitudeNoLatitude for a circular radius search
maxdepthNoLimit to events shallower than this, in kilometres
mindepthNoLimit to events deeper than this, in kilometres
longitudeNoLongitude for a circular radius search
startTimeNoLimit to events on or after this start time. Times use ISO8601 Date/Time format. Unless a timezone is specified, UTC is assumed. Defaults to NOW - 30 days.
maxLatitudeNoNorthern edge of a search rectangle. Minimum values must be less than maximum values. Requests that use both a rectangle and a circle return the intersection, which may be empty.
maxradiuskmNoLimit to events within this many kilometres of the latitude/longitude point
minLatitudeNoSouthern edge of a search rectangle. Minimum values must be less than maximum values. Requests that use both a rectangle and a circle return the intersection, which may be empty.
maxLongitudeNoEastern edge of a search rectangle. Minimum values must be less than maximum values. Requests that use both a rectangle and a circle return the intersection, which may be empty.
maxmagnitudeNoLimit to events with at most this magnitude
minLongitudeNoWestern edge of a search rectangle. Rectangles may cross the date line using minLongitude < -180 or maxLongitude > 180. Minimum values must be less than maximum values. Requests that use both a rectangle and a circle return the intersection, which may be empty.
minmagnitudeNoLimit to events with at least this magnitude

TDQS

A4.1/5.0
Behavior4/5

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

Annotations already declare readOnlyHint=true, so the description adds value by stating 'without returning the events themselves' and positioning the tool for sizing queries. This clarifies the tool's read-only, summary nature beyond what annotations alone provide.

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

Conciseness5/5

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

Two sentences, each earning its place: first states the action, second provides usage context. No filler, front-loaded with the core purpose.

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

Completeness3/5

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

The description covers the action and usage context but does not specify the return format (e.g., returns a number). Since no output schema exists, this omission leaves the agent guessing what the output looks like. Adequate but not complete.

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

Parameters3/5

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

Input schema coverage is 100%, with all 15 parameters having descriptions. The description adds no additional parameter-level information beyond 'matching the given search parameters.' Baseline of 3 is appropriate.

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?

The description clearly states the verb 'Count' and the resource 'earthquakes', and specifies that it does not return events, distinguishing it from sibling tool 'find-earthquakes' which likely returns events. This makes the purpose unmistakable.

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

Usage Guidelines4/5

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

The description provides explicit guidance: 'Useful for sizing a query before running it.' This implies the tool should be used before a search query to gauge result size, and contrasts with sibling tools that return data. However, it doesn't explicitly state when not to use it or name alternatives directly.

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

find-earthquake-detailsFind Earthquake DetailsA
Read-only

Get detailed information about a single earthquake, including origin quality metrics, by its USGS event id (e.g. 'us6000d3zh').

ParametersJSON Schema
NameRequiredDescriptionDefault
eventidYesThe USGS earthquake event id

TDQS

A3.6/5.0
Behavior3/5

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

Annotations already mark readOnlyHint=true and openWorldHint=true, so the description doesn't need to emphasize safe read behavior. It adds that the tool returns 'origin quality metrics', a useful detail beyond annotations, but does not mention pagination, response size, or whether all fields are always present.

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

Conciseness5/5

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

The description is a single, clear sentence with an example inline. Every word is meaningful and there is no filler. Highly front-loaded: key action and parameter type stated immediately.

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

Completeness4/5

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

Given the tool has only 1 parameter, full schema coverage, and informative annotations, the description is nearly complete for a lookup tool. It could mention whether the response is synchronous or if the ID format is always lowercase, but overall it is largely sufficient.

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

Parameters3/5

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

Schema coverage is 100%; the schema already defines eventid as a string with a description. The description adds a concrete example ('us6000d3zh') which aids understanding, but doesn't add deeper semantics beyond what the schema provides. Baseline 3 is appropriate.

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

Purpose4/5

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

The description clearly states the tool gets detailed information for a single earthquake using a specific USGS event ID. The verb 'Get' and resource 'detailed information' are specific, and the example helps differentiate from sibling tools like find-earthquakes which likely return lists.

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

Usage Guidelines3/5

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

The description implies use when you have a specific event ID, but it does not explicitly state when not to use it or contrast with count-earthquakes. The sibling tools exist but no direct guidance on trade-offs is given.

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

find-earthquakesFind EarthquakesB
Read-only

Search the USGS earthquake catalog by time, location, magnitude, and depth. Returns a summary of each matching event.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoMaximum number of events to return (service maximum 20000)
endTimeNoLimit to events on or before this end time. Times use ISO8601 Date/Time format. Unless a timezone is specified, UTC is assumed. Defaults to NOW.
orderbyNoSort order. Defaults to time, most recent first.
latitudeNoLatitude for a circular radius search
maxdepthNoLimit to events shallower than this, in kilometres
mindepthNoLimit to events deeper than this, in kilometres
longitudeNoLongitude for a circular radius search
startTimeNoLimit to events on or after this start time. Times use ISO8601 Date/Time format. Unless a timezone is specified, UTC is assumed. Defaults to NOW - 30 days.
maxLatitudeNoNorthern edge of a search rectangle. Minimum values must be less than maximum values. Requests that use both a rectangle and a circle return the intersection, which may be empty.
maxradiuskmNoLimit to events within this many kilometres of the latitude/longitude point
minLatitudeNoSouthern edge of a search rectangle. Minimum values must be less than maximum values. Requests that use both a rectangle and a circle return the intersection, which may be empty.
maxLongitudeNoEastern edge of a search rectangle. Minimum values must be less than maximum values. Requests that use both a rectangle and a circle return the intersection, which may be empty.
maxmagnitudeNoLimit to events with at most this magnitude
minLongitudeNoWestern edge of a search rectangle. Rectangles may cross the date line using minLongitude < -180 or maxLongitude > 180. Minimum values must be less than maximum values. Requests that use both a rectangle and a circle return the intersection, which may be empty.
minmagnitudeNoLimit to events with at least this magnitude

TDQS

B3.4/5.0
Behavior3/5

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

Annotations already declare readOnlyHint=true (safe read) and openWorldHint=true (data may change). The description adds that it returns a 'summary' (concise, not full detail) and confirms parameters are filters. Bar is lower due to annotations; description adds small value but doesn't explain things like rate limits, pagination, or whether results are sorted by default (the schema says orderby defaults to 'time').

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?

Short single sentence that is front-loaded with the key action ('Search the USGS earthquake catalog...'). No filler or redundancy. Could be slightly improved by noting the return type, but overall concise.

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

Completeness3/5

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

Given the high complexity (15 params, no output schema, rectangle/circle interaction), the description is incomplete. It does not explain return format or behavior beyond 'summary', nor does it document the rectangle-circle intersection behavior visible in the schema. The annotations add value but the description should compensate more for the missing output schema. A 3 reflects this gap.

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

Parameters3/5

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

The schema already has 100% description coverage with detailed explanations for all 15 parameters (e.g., ISO8601 format for time, units for depth/radius, circular vs rectangle logic). The description adds minimal meaning beyond 'earthquake catalog' context. Baseline 3 is appropriate.

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

Purpose4/5

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

The description clearly states the tool searches the USGS earthquake catalog by specific criteria (time, location, magnitude, depth) and returns a summary. It distinguishes from siblings like 'find-earthquake-details' (which likely returns full details) and 'count-earthquakes'. However, it could more explicitly contrast with these siblings.

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

Usage Guidelines3/5

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

The description implies use for searching earthquakes with given filters but provides no guidance on when to prefer this over 'find-earthquake-details' or 'count-earthquakes'. It does not mention when not to use it, e.g., for detailed event info or aggregation queries.

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

Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4/5.0
Disambiguation5/5

Each tool has a clearly distinct purpose: find-earthquakes returns summaries, count-earthquakes returns counts, and find-earthquake-details returns full details for a single ID. There is no overlap or ambiguity.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern (find_earthquakes, count_earthquakes, find_earthquake_details) with snake_case and predictable prefixes, making them easy for an agent to understand and select.

Tool Count5/5

Three tools is ideal for a focused read-only API like the USGS earthquake catalog. Each tool serves a necessary function without redundancy or bloat.

Completeness5/5

The tool set covers the full query lifecycle: search with filtering, count before retrieval, and detailed view by ID. There are no obvious gaps given the read-only nature of the API.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • usgs-earthquakes

    pipeworx-io
    A
    license
    Not graded
    quality
    C
    maintenance
    Provides access to the USGS Earthquake Catalog for querying earthquake events via the FDSNWS API, enabling natural language questions about earthquake data.
    11
    MIT

  • quake-mcp

    adamcwade
    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

Appeared in Searches

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/blake365/usgs-quakes-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server