[![MseeP.ai Security Assessment Badge](https://mseep.net/pr/blake365-usgs-quakes-mcp-badge.png)](https://mseep.ai/app/blake365-usgs-quakes-mcp)

# usgs-quakes-mcp
MCP server for the USGS earthquake catalog

[![npm version](https://img.shields.io/npm/v/usgs-quakes-mcp.svg)](https://www.npmjs.com/package/usgs-quakes-mcp)

An MCP server providing access to the [USGS FDSN event API](https://earthquake.usgs.gov/fdsnws/event/1/)
from [Claude Desktop](https://claude.ai/download), Claude Code, and any other MCP client.

```bash
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.

## 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)

```json
{
  "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)

```json
{
  "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:
```json
{
    "mcpServers": {
        "usgs-quakes": {
            "command": "npx",
            "args": ["-y", "usgs-quakes-mcp"]
        }
    }
}
```

3. Close/Quit then restart Claude Desktop

### Claude Code

```bash
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](https://earthquake.usgs.gov/fdsnws/event/1/).
The service caps any single query at 20,000 events.

## Development

```bash
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.