Tools

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

epa_search_facilities

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

• Geographic filters: ZIP code, state, city (city requires state), or latitude + longitude + radius_miles for proximity search
• 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)

epa_get_ejscreen

Screen a point and its surrounding buffer for environmental-justice indicators.

• Input: latitude, longitude, distance (default 1), and unit (miles or kilometers); kilometers are converted to miles before the request, and the buffer is capped at 15 miles
• Returns the 13 EJScreen environmental indicators (PM2.5, ozone, diesel particulate, NO2, lead paint, traffic proximity, Superfund/RMP/hazardous-waste/wastewater proximity, underground storage tanks, drinking-water non-compliance, RSEI toxic air releases) and 6 demographic indicators (people of color, low income, limited English, less than high school, under 5, over 64)
• Each indicator carries national and state percentiles plus EJ Index values; the Demographic Index and Supplemental Demographic Index are included
• Points outside US coverage return a coverage note instead of fabricated indicators
• Data source: EJScreen v2.2 (2022) served via the community-maintained EJAM API (Public Environmental Data Partners), which rehosts EJScreen after EPA discontinued public access in 2025 — not a live EPA endpoint

Resources and prompts

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:

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

• Multiple environmental data sources unified behind a single epa_ tool surface: ECHO (facility compliance), Envirofacts DMAP (TRI, Superfund, SDWIS), AirNow (real-time air quality), and the community-maintained EJAM API rehosting EJScreen environmental-justice data (v2.2, 2022)
• 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 optional — set AIRNOW_API_KEY to enable epa_get_air_quality (register free at docs.airnowapi.org); without it the server starts with the other 8 tools. ECHO, DMAP, and EJScreen tools work without authentication.

{
  "mcpServers": {
    "epa-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/epa-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "AIRNOW_API_KEY": "your-airnow-key"
      }
    }
  }
}

Or with npx (no Bun required):

{
  "mcpServers": {
    "epa-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/epa-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "AIRNOW_API_KEY": "your-airnow-key"
      }
    }
  }
}

For Streamable HTTP, set the transport and start the server:

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 AIRNOW_API_KEY=... bun run start:http
# Server listens at http://localhost:3010/mcp

Prerequisites

• Bun v1.3.0 or higher (or Node.js v24+).
• (Optional) An AirNow API key to enable epa_get_air_quality — register free at docs.airnowapi.org/account/request. Without it the server runs the other 8 tools. ECHO, DMAP, and EJScreen tools require no API key.

Installation

1. Clone the repository:

git clone https://github.com/cyanheads/epa-mcp-server.git

2. Navigate into the directory:

cd epa-mcp-server

3. Install dependencies:

bun install

4. Configure environment:

cp .env.example .env
# optionally set AIRNOW_API_KEY to enable the air quality tool

Configuration

All configuration is validated at startup via Zod schemas in src/config/. Key environment variables:

See .env.example for the full list of optional overrides.

Running the server

Local development

• Build and run:

  sh

  Copy

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:stdio
  # or
  bun run start:http
  

• Run checks and tests:

  sh

  Copy

  bun run devcheck   # Lint, format, typecheck, security
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec
  

Docker

docker build -t epa-mcp-server .
docker run --rm -e AIRNOW_API_KEY=your-key -p 3010:3010 epa-mcp-server

The Dockerfile defaults to HTTP transport, stateless session mode, and logs to /var/log/epa-mcp-server. OpenTelemetry peer dependencies are installed by default — build with --build-arg OTEL_ENABLED=false to omit them.

Project structure

Development guide

See CLAUDE.md for development guidelines and architectural rules. The short version:

• Handlers throw, framework catches — no try/catch in tool logic
• Use ctx.log for request-scoped logging, ctx.state for tenant-scoped storage
• Register new tools and resources via the barrels in src/mcp-server/*/definitions/index.ts
• Wrap external API calls: validate raw → normalize to domain type → return output schema; never fabricate missing fields
• ECHO searches must enforce at least one geographic parameter — unscoped queries time out against the live API

Contributing

Issues and pull requests are welcome. Run checks and tests before submitting:

bun run devcheck
bun run test

License

Apache-2.0 — see LICENSE for details.