mcp-hazards

An MCP 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
weather_alerts	lat, lon	NWS API /alerts/active
point_forecast	lat, lon	NWS API /points → gridpoint forecast
recent_earthquakes	lat, lon, radius_km=100, days=30, min_magnitude=2.5	USGS FDSN Event Service
flood_zone	lat, lon	FEMA National Flood Hazard Layer (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+.

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

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

Use with Claude Desktop

Add to claude_desktop_config.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 — pytest never touches a live API.

.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:

.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