convez.ai
MCP ServerDados & AnalyticsIntermediário
cyanheads

EPA MCP Server

cyanheads/epa-mcp-server

Dados ambientais EPA — compliance, tóxicos, Superfund e qualidade do ar

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP que fornece acesso a dados ambientais da EPA (Agência de Proteção Ambiental dos EUA), incluindo conformidade de instalações (ECHO), liberações tóxicas (TRI), sites Superfund, sistemas de água potável e qualidade do ar em tempo real (AirNow). Implementado em TypeScript com suporte a STDIO e HTTP Streamable.

Instalação

$npx convez-ai cyanheads/epa-mcp-server

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
2
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 3 dias
Versão
v0.8.1
Issues abertas
4
Contribuidores
1

Casos de uso

  • Pesquisa de conformidade ambiental de instalações industriais
  • Monitoramento de qualidade do ar em tempo real para regiões específicas
  • Análise de dados de liberações tóxicas e ações de enforcement
  • Avaliação de risco ambiental para localidades e operações

Veredito

MCP server bem estruturado e production-ready para integrar dados ambientais públicos da EPA em aplicações Claude. Excelente para compliance, pesquisa ambiental e análise de qualidade do ar, com 8 ferramentas bem definidas e suporte multi-plataforma (Docker, npm, STDIO/HTTP).

README

A tradução para o português deste README ainda está na fila.

Version License Docker MCP SDK npm TypeScript Bun

Install in Claude Desktop Install in Cursor Install in VS Code

Framework


Tools

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

ToolDescription
epa_search_facilitiesSearch 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_facilityRetrieve 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_violationsSearch 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_qualityGet 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_releasesQuery Toxic Release Inventory annual chemical release data for a specific facility by medium (air, water, land, underground injection) and reporting year.
epa_search_tri_releasesSearch 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_superfundSearch 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_systemsSearch 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

TypeNameDescription
Resourceepa://facility/{registry_id}Full compliance profile for a facility by EPA Registry ID (same data as epa_get_facility)
Resourceepa://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:

  • 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. ECHO and DMAP 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

Installation

  1. Clone the repository:
git clone https://github.com/cyanheads/epa-mcp-server.git
  1. Navigate into the directory:
cd epa-mcp-server
  1. Install dependencies:
bun install
  1. Configure environment:
cp .env.example .env
# edit .env and set AIRNOW_API_KEY

Configuration

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

VariableDescriptionDefault
AIRNOW_API_KEYRequired for epa_get_air_quality. Free registration at docs.airnowapi.org. ECHO and DMAP tools work without it.—
EPA_ECHO_BASE_URLECHO API base URLhttps://echodata.epa.gov/echo
EPA_DMAP_BASE_URLEnvirofacts DMAP API base URLhttps://data.epa.gov/dmapservice
EPA_AIRNOW_BASE_URLAirNow API base URLhttps://www.airnowapi.org/aq
MCP_TRANSPORT_TYPETransport: stdio or httpstdio
MCP_HTTP_PORTHTTP server port3010
MCP_HTTP_ENDPOINT_PATHHTTP endpoint path/mcp
MCP_AUTH_MODEAuth mode: none, jwt, or oauthnone
MCP_LOG_LEVELLog level (RFC 5424)info
LOGS_DIRDirectory for log files (Node.js only)<project-root>/logs
STORAGE_PROVIDER_TYPEStorage backend: in-memory, filesystem, supabase, cloudflare-kv/r2/d1in-memory
OTEL_ENABLEDEnable OpenTelemetry tracing and metricsfalse

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

Running the server

Local development

  • Build and run:

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

    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

DirectoryPurpose
src/index.tscreateApp() entry point — registers tools/resources and inits services.
src/configServer-specific environment variable parsing and validation with Zod.
src/mcp-server/toolsTool definitions (*.tool.ts). Eight tools across ECHO, DMAP, and AirNow.
src/mcp-server/resourcesResource definitions (*.resource.ts). Facility and Superfund URI handlers.
src/services/echoECHO REST API service layer — facility search, facility detail, enforcement cases.
src/services/dmapEnvirofacts DMAP service layer — TRI releases, Superfund sites, drinking water systems.
src/services/airnowAirNow service layer — current and forecast AQI observations.
tests/Unit and integration tests mirroring src/.

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.

Ver o original no GitHub

Bom para

Relacionados