epa-mcp-server

<div align="center">
  <h1>@cyanheads/epa-mcp-server</h1>
  <p><b>Access EPA environmental data — facility compliance (ECHO), toxic releases (TRI), Superfund sites, drinking water systems, and real-time air quality (AirNow) via MCP. STDIO or Streamable HTTP.</b>
  <div>8 Tools • 2 Resources</div>
  </p>
</div>

<div align="center">

[![Version](https://img.shields.io/badge/Version-0.1.5-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/epa-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^1.29.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/epa-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/epa-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^6.0.3-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.3.0-blueviolet.svg?style=flat-square)](https://bun.sh/)

</div>

<div align="center">

[![Install in Claude Desktop](https://img.shields.io/badge/Install_in-Claude_Desktop-D97757?style=for-the-badge&logo=anthropic&logoColor=white)](https://github.com/cyanheads/epa-mcp-server/releases/latest/download/epa-mcp-server.mcpb) [![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=epa-mcp-server&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBjeWFuaGVhZHMvZXBhLW1jcC1zZXJ2ZXIiXSwiZW52Ijp7IkFJUk5PV19BUElfS0VZIjoieW91ci1hcGkta2V5In19) [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=for-the-badge&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect?url=vscode:mcp/install?%7B%22name%22%3A%22epa-mcp-server%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40cyanheads%2Fepa-mcp-server%22%5D%2C%22env%22%3A%7B%22AIRNOW_API_KEY%22%3A%22your-api-key%22%7D%7D)

[![Framework](https://img.shields.io/badge/Built%20on-@cyanheads/mcp--ts--core-67E8F9?style=flat-square)](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)

</div>

---

## Tools

8 tools spanning EPA facility compliance, toxic chemical releases, Superfund cleanup sites, drinking water safety, and real-time air quality:

| Tool | Description |
|:---|:---|
| `epa_search_facilities` | Search EPA-regulated facilities by location, industry, or compliance status across all environmental programs (CAA, CWA, RCRA, TRI, SDWA). Returns facility name, EPA Registry ID, coordinates, county FIPS, per-program compliance flags, inspection counts, penalty totals, and TRI release totals. |
| `epa_get_facility` | Retrieve a full compliance profile for a single EPA-regulated facility: compliance status per program, inspection dates, formal enforcement actions, penalty amounts, and TRI annual release totals. Aggregates multiple ECHO DFR endpoints in parallel. |
| `epa_search_violations` | Search EPA civil and criminal enforcement cases by state, regulatory program, or date range. Returns case identifier, facility name and Registry ID, programs involved, penalty assessed, settlement date, and case type. |
| `epa_get_air_quality` | Get AQI observations or forecasts for a location. Returns per-pollutant AQI values (PM2.5, ozone, CO, SO2, NO2), AQI category (Good through Hazardous), reporting area name, and observation timestamp. |
| `epa_get_tri_releases` | Query Toxic Release Inventory annual chemical release data for a specific facility by medium (air, water, land, underground injection) and reporting year. |
| `epa_search_tri_releases` | Search Toxic Release Inventory data across facilities in a state or county for a given year. Returns facility name, TRI ID, chemical name, total releases by medium, and facility coordinates. |
| `epa_search_superfund` | Search Superfund (CERCLA/SEMS) sites by location or NPL listing status. Accepts state/city/ZIP or lat/lng + radius for proximity searches. Returns site name, EPA ID, NPL status, cleanup status, and coordinates. |
| `epa_search_water_systems` | Search drinking water systems (SDWIS) by state or ZIP code. Returns system name, PWSID, population served, primary water source, and active violation status. |

### `epa_search_facilities`

Search for EPA-regulated facilities with cross-program compliance data.

- Geographic filters: ZIP code, state, city (city requires state)
- Program filter: narrow to CAA, CWA, RCRA, TRI, or SDWA registrants
- Compliance filter: `has_violation` flag to surface only non-compliant facilities
- Returns `RegistryID` (key for `epa_get_facility`), `FacFIPSCode` (county FIPS for Census chaining), and coordinates
- Results cap enforced — unscoped searches are prohibited at the input validation layer

---

### `epa_get_facility`

Retrieve a comprehensive compliance profile by EPA Registry ID.

- Aggregates 3–5 ECHO DFR endpoints in parallel: program flags and TRI totals, compliance summary, inspection/enforcement history, CAA details (if registered), CWA/NPDES permit details (if registered)
- Uses `Promise.allSettled` — partial data returned even if one upstream endpoint fails
- Includes formal enforcement actions, penalty amounts, and inspection dates across all programs

---

### `epa_search_violations`

Search area-level EPA enforcement cases — distinct from per-facility history in `epa_get_facility`.

- Program filter: CAA, CWA, RCRA, SDWA, CERCLA, FIFRA, or TSCA
- Case type: civil, criminal, or all
- Date range filtering by filing date (ISO 8601)
- Returns case identifier, affected facility name and Registry ID for downstream `epa_get_facility` lookup

---

### `epa_get_air_quality`

Get current AQI observations or daily forecasts from AirNow.

- Accepts ZIP code or latitude/longitude coordinates
- `mode: current` returns the latest observed AQI per pollutant; `mode: forecast` returns daily AQI forecasts (requires `forecast_date`)
- AQI categories: Good (1) through Hazardous (6) with numeric and text category
- Data is preliminary — suitable for awareness, not regulatory or enforcement decisions
- AirNow responses cached at ~1 hour TTL to respect rate limits

---

### `epa_get_tri_releases`

Query per-chemical release breakdown for a single TRI facility.

- Accepts TRI facility ID from `epa_search_facilities` results
- Returns release quantities by medium: air, water, land, underground injection
- Optional year filter (defaults to most recent available); optional chemical name filter
- TRI data lags ~18 months — most recent available year is typically 2 years prior to current

---

### `epa_search_tri_releases`

Identify top polluters in a region via TRI data.

- State and optional county scope; required year parameter
- Optional chemical name filter to focus on a specific substance
- Returns facility coordinates for downstream map or proximity analysis
- Complement to `epa_get_tri_releases` — use this for area discovery, then drill into a specific facility

---

### `epa_search_superfund`

Search Superfund (CERCLA/SEMS) sites by location or proximity.

- Two input shapes: state/city/ZIP for administrative filters, or lat/lng + radius for proximity
- NPL status filter: listed, not-listed, proposed, or all
- Returns site cleanup status and coordinates for downstream spatial analysis

---

### `epa_search_water_systems`

Identify drinking water systems with active or recent violations.

- State and optional ZIP code scope
- `has_violation` flag surfaces only systems with current violations
- PWS type filter: community (`CWS`), non-transient non-community (`NTNCWS`), or transient non-community (`TNCWS`)

## Resources and prompts

| Type | Name | Description |
|:---|:---|:---|
| Resource | `epa://facility/{registry_id}` | Full compliance profile for a facility by EPA Registry ID (same data as `epa_get_facility`) |
| Resource | `epa://superfund/{site_id}` | Superfund site record by SEMS site ID |

All resource data is also reachable via tools. Use `epa_get_facility` and `epa_search_superfund` for programmatic access in tool-only MCP clients.

## Features

Built on [`@cyanheads/mcp-ts-core`](https://www.npmjs.com/package/@cyanheads/mcp-ts-core):

- Declarative tool and resource definitions — single file per primitive, framework handles registration and validation
- Unified error handling — handlers throw, framework catches, classifies, and formats
- Pluggable auth: `none`, `jwt`, `oauth`
- Swappable storage backends: `in-memory`, `filesystem`, `Supabase`, `Cloudflare KV/R2/D1`
- Structured logging with optional OpenTelemetry tracing
- STDIO and Streamable HTTP transports

EPA-specific:

- Three complementary EPA APIs unified behind a single `epa_` tool surface: ECHO (facility compliance), Envirofacts DMAP (TRI, Superfund, SDWIS), and AirNow (real-time air quality)
- Parallel ECHO DFR aggregation in `epa_get_facility` — 3–5 upstream calls resolved concurrently with `Promise.allSettled`
- AirNow response caching (~1 hour TTL) to stay within per-key rate limits
- DMAP coordinate normalization — `tri.tri_facility` DDMMSS integers converted to decimal degrees

Agent-friendly output:

- Cross-tool join keys surfaced on every response — `RegistryID` and `FacFIPSCode` from facility search feed directly into compliance, TRI, and Census API workflows
- Typed enforcement and compliance status fields — agents branch on data values, not string parsing
- Structured partial failure — `epa_get_facility` returns available program data even when one DFR endpoint is unavailable, with per-section status

## Getting started

Add the following to your MCP client configuration file. An AirNow API key is required for `epa_get_air_quality` — register free at [docs.airnowapi.org](https://docs.airnowapi.org/account/request/). ECHO and DMAP tools work without au