Geohazard MCP

An open-source MCP server that aggregates real-time environmental and natural-hazard data from 12 public sources into a unified risk assessment. Point any MCP-compatible client (Claude Desktop, Cursor, your own agent) at the server and query planetary conditions by coordinate.

Data Sources

Source	Layer
Open-Meteo	Weather (temperature, wind, precipitation, UV)
Open-Meteo AQ	Air quality forecasts (PM2.5, PM10, O3, NO2)
OpenAQ	Physical air quality station measurements
USGS Earthquake	Seismic events — 7-day lookback with Omori decay
NASA FIRMS	Fire hotspots (density + nearest proximity, VIIRS confidence-filtered)
GloFAS (Copernicus)	Flood discharge forecasts
NOAA NWS	Severe weather alerts (US / PR / VI / Guam only)
NOAA SWPC	Space weather (Kp index, geomagnetic storms)
NOAA Tsunami	Active tsunami warnings
Smithsonian GVP	Volcanic activity with alert-level × proximity scoring
CMEMS (Copernicus)	Marine conditions (SST, wave height, currents)
GDACS	Global disaster alerts — contributes cyclone score to the weather layer

All sources are free/public. NASA FIRMS and OpenAQ need API keys (free to register) — without them those layers are skipped. OpenAQ and Open-Meteo AQ are distance-weighted and blended into a single air quality result with pollutants normalized to the US EPA AQI scale so cross-source comparisons are meaningful.

Each source is wired through a central registry (src/sources/registry.ts) that declares its fetch function, freshness window, applicability predicate, and — where relevant — its risk-scoring hook. Adding a new source is ~3 files.

Risk Scoring

The overall risk score (0–1) is a weighted sum of per-layer scores, with two safeguards:

• Critical override: if any single layer scores ≥ 0.9, the overall score is at least 0.7 (high). If any layer scores ≥ 0.75, at least 0.5 (moderate). This prevents a catastrophic single-hazard event from being diluted by calm conditions elsewhere.
• Omori seismic decay: earthquake risk uses a modified Omori model based on actual event time rather than flat exponential decay. Large earthquakes (M6+) maintain elevated risk for days 0–3 reflecting real aftershock patterns.

Layer weights (declared in the registry):

Layer	Weight	Contributing source(s)
Seismic	0.25	USGS Earthquake
Weather	0.20	Open-Meteo, GDACS (cyclone)
Fire	0.20	NASA FIRMS
Flood	0.15	GloFAS
Air quality	0.10	OpenAQ + Open-Meteo AQ (blended)
Space weather	0.05	NOAA SWPC
Volcanic	0.05	Smithsonian GVP

Level	Score
Critical	≥ 0.80
High	≥ 0.60
Moderate	≥ 0.35
Low	≥ 0.15
Minimal	< 0.15

Confidence Scoring

Confidence is the fraction of location-applicable sources that returned fresh, ok data:

overall = okCount / applicableCount

• Applicability: a source is counted only if its scope covers the query location. In practice this only excludes NOAA NWS outside the US/PR/VI/Guam (where api.weather.gov hard-fails with 404). Every other source is global; its own ok signal is trusted.
• Staleness: a source is counted as failed if its data is older than 2 × freshnessMinutes (freshness windows live in the registry).
• Shape: ConfidenceScore exposes applicableSources, okSources, failedSources, and notApplicableSources so clients can see exactly which sources contributed.

Level	Score
Reliable	≥ 0.80
Partial	≥ 0.60
Limited	≥ 0.40
Estimate	< 0.40

Discrepancies

Cross-source disagreements are detected separately and surfaced on AggregatedConditions.discrepancies (and on compare_sources). Discrepancies between sources that are intentionally blended (e.g. OpenAQ vs Open-Meteo AQ) are tagged expected: true and don't influence downstream interpretation. Discrepancies no longer penalise the confidence score — they stand on their own for UI-level auditing.

MCP Tools

Tool	Description
get_conditions	Real-time environmental conditions at a coordinate
get_alerts	Active natural-hazard alerts nearby (seismic, fire, severe weather, tsunami, cyclones)
get_risk_assessment	Overall risk score and per-layer breakdown
get_forecast	Multi-hazard forecast with per-day risk and confidence (up to 16 days)
compare_sources	Raw per-source data plus detected discrepancies for auditing

Quick Start

Use with Claude Desktop / Cursor

Add to your MCP client config:

{
  "mcpServers": {
    "geohazard": {
      "command": "npx",
      "args": ["-y", "geohazard-mcp"],
      "env": {
        "NASA_FIRMS_KEY": "your-key-here",
        "OPENAQ_API_KEY": "your-key-here"
      }
    }
  }
}

Windows: use "command": "npx.cmd" instead of "command": "npx".

API keys are optional — without them those layers are skipped. Register for free: NASA FIRMS · OpenAQ.

Use with Docker

docker compose up

The container starts on port 3000 with HTTP transport. Pass API keys via environment variables in docker-compose.yml or a .env file.

Configuration

Variable	Default	Description
NASA_FIRMS_KEY	—	NASA FIRMS API key — fire layer skipped if unset
OPENAQ_API_KEY	—	OpenAQ API key — station AQ layer skipped if unset
CACHE_TTL_SECONDS	300	In-memory cache TTL
DEFAULT_RADIUS_KM	500	Default search radius for nearby events (seismic lookback is 7 days)
MCP_PORT	3000	HTTP server port
MCP_TRANSPORT	stdio	stdio or http
MCP_ALLOWED_ORIGINS	—	Comma-separated CORS origins
LOG_DIR	./logs	Directory for discrepancy and request logs
LOG_LEVEL	info	Log verbosity

Development

Prerequisites

• Node.js >= 20
• pnpm >= 10

Setup

git clone https://github.com/PMFrancisco/geohazard-mcp.git
cd geohazard-mcp
pnpm install
cp .env.example .env   # edit to add optional API keys

Run locally

pnpm dev:server        # HTTP transport on :3000
pnpm dev               # Quick smoke test (prints conditions for Madrid)

Code quality

pnpm typecheck    # Type-check without emitting
pnpm lint         # ESLint
pnpm format       # Prettier (write)
pnpm build        # Compile to dist/

Commits follow Conventional Commits enforced by commitlint and husky.

Project Structure

src/
  types/          Shared TypeScript interfaces
  sources/
    registry.ts   Source registry: fetch wiring, freshness, applicability, risk hooks
    http.ts       fetchWithTimeout + sourceError helpers shared by every adapter
    aqi.ts        US EPA AQI computation + unit conversions
    *.ts          One adapter per external data source
  aggregator/
    index.ts      Registry-driven fan-out; merges sources into AggregatedConditions
    riskScore.ts  Per-layer score functions + weighted rollup with critical override
    forecast.ts   Multi-day risk/confidence projection
    compareSources.ts  Cross-source discrepancy detection
  confidence/
    static.ts     okCount / applicableCount, with staleness cutoff
  logger/
    discrepancy.ts  JSONL discrepancy log writer
  server/
    tools/        MCP tool definitions (one file per tool + registry)
    middleware/   CORS, rate limiting, request logging
    http.ts       Express wrapper for HTTP transport
    index.ts      MCP entry point (stdio or HTTP based on MCP_TRANSPORT)
  index.ts        Library export + Madrid smoke test

Testing

pnpm test            # Run the full suite
pnpm test:watch      # Re-run on change
pnpm test:coverage   # HTML coverage report under coverage/

The suite is Vitest + supertest and is organized in three tiers under tests/:

Tier	Location	What it covers
Unit	tests/aggregator/, tests/confidence/	Pure scoring, confidence, discrepancy-detection logic
Adapters	tests/sources/	One file per source — global.fetch is stubbed and a fixture asserts normalization of the upstream schema
Server	tests/server/	supertest against buildHttpApp with the aggregator mocked, covering routing, Zod validation, middleware, and tool wiring

No live API calls are made. NASA FIRMS and OpenAQ API keys are mocked at the environment level, so the suite runs fully offline.

License

Apache 2.0 — see LICENSE.