# mcp-hazards

An [MCP](https://modelcontextprotocol.io) server that gives AI agents grounded access to US natural-hazard data — weather alerts, forecasts, earthquakes, and FEMA flood zones — from free, keyless US government APIs. Hazard questions ("Is this address in a flood zone?", "Any warnings near the job site today?") are exactly where an LLM should not guess: the answers exist, they're authoritative, and they change hourly. This server turns those questions into schema-validated tool calls with typed Pydantic outputs, bounded inputs, and honest error messages — no API keys, no scraping, no hallucinated risk assessments.

## Tools

| Tool | Inputs | Source API |
|---|---|---|
| `geocode_address` | `address` | [US Census Geocoder](https://geocoding.geo.census.gov/) |
| `weather_alerts` | `lat`, `lon` | [NWS API](https://www.weather.gov/documentation/services-web-api) `/alerts/active` |
| `point_forecast` | `lat`, `lon` | [NWS API](https://www.weather.gov/documentation/services-web-api) `/points` → gridpoint forecast |
| `recent_earthquakes` | `lat`, `lon`, `radius_km=100`, `days=30`, `min_magnitude=2.5` | [USGS FDSN Event Service](https://earthquake.usgs.gov/fdsnws/event/1/) |
| `flood_zone` | `lat`, `lon` | [FEMA National Flood Hazard Layer](https://hazards.fema.gov/) (ArcGIS REST) |

`flood_zone` translates FEMA zone codes into plain English: **A/AE/AH/AO/AR/A99** and **V/VE** are high-risk Special Flood Hazard Areas, **shaded X** (0.2% annual chance) is moderate, **unshaded X** is minimal, **D** is undetermined.

All tools validate inputs up front (latitude/longitude ranges, bounded radius/days/magnitude) and return explicit messages for empty results rather than empty payloads.

## Install

Requires Python 3.11+.

```bash
git clone https://github.com/jsuich/mcp-hazards.git
cd mcp-hazards
python3 -m venv .venv
.venv/bin/pip install -e .
```

## Use with Claude Code

```bash
claude mcp add hazards -- /absolute/path/to/mcp-hazards/.venv/bin/mcp-hazards
```

## Use with Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "hazards": {
      "command": "/absolute/path/to/mcp-hazards/.venv/bin/mcp-hazards"
    }
  }
}
```

## Example prompts

- "Any active weather alerts for 123 Main St, Augusta GA?"
- "What's the forecast for the next few days at Lake Tahoe (39.09, -120.03)?"
- "List magnitude 3+ earthquakes within 200 km of San Jose in the last 90 days."
- "Is 400 Royal St, New Orleans in a FEMA flood zone? What does the zone mean?"

## Testing

Tests are fully network-mocked with [respx](https://lundberg.github.io/respx/) — `pytest` never touches a live API.

```bash
.venv/bin/pip install -e ".[dev]"
.venv/bin/python -m pytest -q
```

A separate live smoke script (not part of the test suite) exercises the real endpoints:

```bash
.venv/bin/python scripts/live_smoke.py
```

## Data sources and disclaimer

Data is provided by the US Census Bureau, National Weather Service (NOAA), US Geological Survey, and FEMA via their public APIs. This project is not affiliated with or endorsed by any of these agencies. Upstream data can be delayed, incomplete, or revised.

**Do not use this software for life-safety decisions.** For emergencies and official guidance, rely on local authorities, NOAA Weather Radio, and official agency channels.

## License

MIT © 2026 Josh Suich