# quake-mcp

An MCP server for the [USGS Earthquake Hazards API](https://earthquake.usgs.gov/fdsnws/event/1/). It lets AI assistants search the global earthquake catalog, look up event details, count quakes, find "Did You Feel It" reports, and read the USGS realtime feeds. No API key required.

## What is MCP?

The [Model Context Protocol](https://modelcontextprotocol.io) (MCP) is an open standard that lets AI assistants like Claude connect to external tools and data sources. An MCP server exposes a set of tools and resources over a simple transport (here, stdio); any MCP-capable client (Claude Desktop, Claude Code, Cursor, and others) can launch the server and call its tools during a conversation, so the assistant can answer questions with live data instead of stale training knowledge.

## What this server does

quake-mcp wraps the public USGS earthquake catalog and realtime feeds:

- Search earthquakes by time range, magnitude range, bounding box, or center point plus radius
- Get full details for a specific event by id (depth, intensity, PAGER alert, tsunami flag, felt reports)
- List significant earthquakes from the last N days
- Count earthquakes matching a query without listing them
- Find quakes with "Did You Feel It" citizen reports near a location
- Read the USGS realtime feed summaries (past hour, day, and week) as MCP resources

Output is formatted, truncated to a sane size for LLM context windows, and includes USGS event ids and links for follow-up.

## Install

Run directly with npx (recommended, nothing to install):

```bash
npx quake-mcp
```

Or install globally:

```bash
npm install -g quake-mcp
```

Requires Node.js 20 or newer.

## Configuration

### Claude Desktop

Add to `claude_desktop_config.json` (Settings, Developer, Edit Config):

```json
{
  "mcpServers": {
    "quake": {
      "command": "npx",
      "args": ["-y", "quake-mcp"]
    }
  }
}
```

### Claude Code

```bash
claude mcp add quake -- npx -y quake-mcp
```

### Cursor

Add to `.cursor/mcp.json` in your project (or `~/.cursor/mcp.json` globally):

```json
{
  "mcpServers": {
    "quake": {
      "command": "npx",
      "args": ["-y", "quake-mcp"]
    }
  }
}
```

## Tools

### search_earthquakes

Search the USGS catalog. All parameters are optional; the default is the past 30 days, worldwide, newest first.

| Parameter | Type | Description |
| --- | --- | --- |
| `start_time` | string | ISO 8601 start of the time window. Default: 30 days ago. |
| `end_time` | string | ISO 8601 end of the time window. Default: now. |
| `min_magnitude` | number | Minimum magnitude, e.g. 5 for M5+. |
| `max_magnitude` | number | Maximum magnitude. |
| `min_latitude`, `max_latitude` | number | Bounding box edges in decimal degrees. |
| `min_longitude`, `max_longitude` | number | Bounding box edges in decimal degrees. |
| `latitude`, `longitude`, `radius_km` | number | Circle search: center point and radius in km. All three required together. |
| `limit` | integer | Max events to return, 1 to 200. Default 25. |
| `orderby` | string | `time` (default), `time-asc`, `magnitude`, `magnitude-asc`. |

Example prompts:

- "Show me all M5+ earthquakes near Japan this week"
- "List the 10 largest earthquakes in the last month, sorted by magnitude"
- "Any earthquakes within 200 km of Mexico City since June 1?"

### get_earthquake

Full details for one event.

| Parameter | Type | Description |
| --- | --- | --- |
| `event_id` | string | USGS event id, e.g. `us7000abcd` (returned by the search tools). |

Example prompts:

- "Get the details for earthquake us7000srcg"
- "Was there a tsunami warning for that quake?"

### recent_significant

Significant earthquakes from the last N days, using the USGS significance score (the same threshold as the official significant events feed).

| Parameter | Type | Description |
| --- | --- | --- |
| `days` | integer | How many days back to look, 1 to 365. Default 7. |
| `limit` | integer | Max events, 1 to 200. Default 25. |

Example prompts:

- "What were the significant earthquakes this week?"
- "Any major quakes in the last 30 days?"

### count_earthquakes

Count matching events without listing them. Accepts the same time, magnitude, and location filters as `search_earthquakes` (minus `limit` and `orderby`).

Example prompts:

- "How many M4.5+ earthquakes happened worldwide in the last 30 days?"
- "How many quakes hit within 500 km of Tokyo this year?"

### felt_reports

Earthquakes near a location with "Did You Feel It" (DYFI) citizen reports.

| Parameter | Type | Description |
| --- | --- | --- |
| `latitude` | number | Center latitude (required). |
| `longitude` | number | Center longitude (required). |
| `radius_km` | number | Search radius in km. Default 300. |
| `days` | integer | How many days back to look. Default 30. |
| `min_felt` | integer | Minimum number of felt reports. Default 1. |
| `limit` | integer | Max events. Default 25. |

Example prompts:

- "Did anyone feel an earthquake near San Francisco this week?"
- "Which quakes near Los Angeles got the most felt reports this month?"

## Resources

The server exposes USGS realtime feed summaries as readable resources:

| URI | Feed |
| --- | --- |
| `usgs://feeds/significant/day` | Significant earthquakes, past day |
| `usgs://feeds/significant/week` | Significant earthquakes, past week |
| `usgs://feeds/4.5/day` | M4.5+ earthquakes, past day |
| `usgs://feeds/4.5/week` | M4.5+ earthquakes, past week |
| `usgs://feeds/2.5/day` | M2.5+ earthquakes, past day |
| `usgs://feeds/1.0/hour` | M1.0+ earthquakes, past hour |

## Development

```bash
git clone https://github.com/adamcwade/quake-mcp.git
cd quake-mcp
npm install
npm run build     # compile TypeScript to dist/
npm test          # run unit tests (vitest)
node scripts/smoke.mjs   # end-to-end test against the live USGS API
```

To try the server interactively, use the MCP Inspector:

```bash
npx @modelcontextprotocol/inspector node dist/index.js
```

## Publishing

`npm publish` runs the build automatically via `prepublishOnly`. Only `dist/`, `README.md`, and `LICENSE` are included in the package.

## Notes

- Data comes from the USGS Earthquake Hazards Program and is in the public domain. This project is not affiliated with or endorsed by USGS.
- The USGS API asks clients to be reasonable with request rates; this server sends a descriptive User-Agent and caps result sizes.

## License

MIT, copyright 2026 Adam Wade. See [LICENSE](LICENSE).