Skip to main content
Glama
@cyanheads/epa-drinking-water-mcp-server

@cyanheads/epa-drinking-water-mcp-server

by cyanheads

Version License Docker MCP SDK npm TypeScript Bun

Install in Claude Desktop Install in Cursor Install in VS Code

Framework


Overview

EPA drinking-water records from SDWIS DMAP and the UCMR 5 publication. Resolve water systems, inspect historical violations and enforcement, and retrieve Lead and Copper Rule summaries or unregulated-contaminant occurrence measurements. Runs over stdio or Streamable HTTP without an API key.

Tools

Tool

Description

sdwis_list_reference

Decode identifiers, contaminant namespaces, coverage, standards, and EPA dictionaries

sdwis_search_water_systems

Find contact-free public water-system inventory

sdwis_get_system_profile

Retrieve summary, geography, service areas, facilities, or treatment

sdwis_get_violations

Page reported historical SDWA violations

sdwis_search_contaminants

Select violations, LCR summaries, or UCMR 5 occurrence

sdwis_get_enforcement_actions

Retrieve actions or violation associations

sdwis_dataframe_describe

Inspect tables and provenance inside a supplied canvas

sdwis_dataframe_query

Run read-only SQL against staged partitions

sdwis_dataframe_drop

Optionally remove one staged table

The dataframe tools require npm or Docker with CANVAS_PROVIDER_TYPE=duckdb; drop also requires SDWIS_DATAFRAME_DROP_ENABLED=true. The Claude Desktop bundle provides the six EPA-reading tools.

The published caller guide covers evidence chains and staged analysis. Plugin, npm, Docker, and MCPB installs include it; MCP clients can read skill://epa-drinking-water-guide/SKILL.md through the Skills extension.

Related MCP server: duckdb-mcp

Capability reference

sdwis_list_reference tool

  • Required topic: identifiers, system_types, sources, contaminants, violation_types, enforcement_types, treatment, service_areas, standards, or coverage; optional substring query

  • Interpretation topics are bundled; dictionaries are live. SDWIS codes and UCMR analytes remain separate namespaces; standards explain MCL, MCLG, and action levels without classifying historical records as exceedances


sdwis_search_water_systems tool

  • At least one narrowing selector: pwsid, name_contains, state, county (requires state), population_min / population_max, source, system_type, school_or_daycare, primacy_agency, or pwsid_prefix; names match literal case-insensitive substrings and counties match normalized names exactly, including punctuation

  • activity defaults to active; choose inactive or all explicitly. State means reported legal-entity state; county means county served, and neither establishes complete physical service boundaries

  • school_or_daycare:true selects reported Y, false selects N; unknown indicators match neither. Discovery and profile summaries preserve school/daycare and wholesaler source indicators; this is not an inventory of every school receiving public water


sdwis_get_system_profile tool

  • Required nine-character alphanumeric pwsid; section is summary (default), geography, service_areas, facilities, or treatment, independently paged

  • Summary returns system with empty items and returned:0; child sections return items. found tracks inventory existence: an empty child section can still return found:true with an empty-section notice. found:false is not a compliance finding; operator contacts and mailing addresses are excluded

  • Facilities resolve SDWIS treatment/violation facility_id values within the same PWSID; optional exact facility_id is valid only for this section. SDWIS and UCMR facility IDs are separate namespaces


sdwis_get_violations tool

  • Require pwsid or state; optional county, contaminant, category, health_based, and compliance_status

  • Inclusive date_from / date_to select compliance-period overlap; a known endpoint can prove overlap despite a missing endpoint. Indeterminate periods are excluded with a count of affected rows examined during the call. Monitoring/reporting violations may lack concentrations

  • contaminant:lead selects 1030 and Lead and Copper Rule code 5000, including copper and monitoring records; either exact code selects only itself

  • stage:true requests a partition; stage_max_rows defaults to 5,000 and clamps at 25,000. Supply a held canvas_id to add another partition


sdwis_search_contaminants tool

  • Require dataset (violations, lcr, or ucmr5) and pwsid or state; UCMR also accepts zip alone without SDWIS membership requests. Additional selectors intersect; county still requires state. Optional contaminant and inclusive dates select compliance periods, LCR sample periods, or UCMR collection dates respectively

  • LCR lead/copper select PB90/CU90 summaries, not household samples. UCMR PFAS covers 29 analytes; lithium is separate. zip and detected_only are UCMR-only; service ZIP is not sample location, and censored values remain unknown below reporting limits

  • Supports stage, canvas_id, and stage_max_rows (5,000 default, 25,000 maximum). Cold UCMR calls may need a 180-second client timeout; broad state/county scopes resolve reported-state membership through resumable pages before returning occurrence rows


sdwis_get_enforcement_actions tool

  • Actions require pwsid or reported legal-entity state, with optional state-qualified county; geographic membership resolves before action retrieval. section:associations and any violation_id filter require pwsid; supplied geography still intersects that system

  • action_type, originator, and inclusive enforcement-date filters apply only to actions. Associations page separately; source action text does not imply a federal order or monetary penalty

  • Action types match the complete published code exactly and case-insensitively, including punctuation; missing dictionary labels remain null

  • Supports stage, canvas_id, and stage_max_rows (5,000 default, 25,000 maximum)


sdwis_dataframe_describe tool

  • Required caller-held canvas_id; optional exact table_name; limit defaults to 10 with a cap of 500 and cursor pagination

  • One whole table per item includes its columns array, row count, expiry, filters, provenance, completeness, and continuation; counts and limits are in tables. There is no global canvas listing

  • Describe continuations retain their original deadline (at most 15 minutes or table expiry when issued) and reject changed membership, rows, schema, or lineage. Query-driven TTL extensions preserve cursor identity; responses report current authoritative expiry

  • selection_coverage reports which source partitions and required companion relations remain staged, separately from SQL results


sdwis_dataframe_query tool

  • Required canvas_id and one read-only SELECT, WITH, or FROM statement in sql (at most 20,000 characters); describe the canvas first

  • Retains at most CANVAS_DEFAULT_ROW_LIMIT (framework default 10,000), bounded by 25,000. row_count, truncated, and has_more distinguish retained rows from omitted rows; continuations read an immutable result for up to 15 minutes

  • File, network, write, and system-catalog access are refused. source_complete conservatively includes every live source partition, including tables the SQL does not reference

  • Known caller-correctable SQL errors preserve path-redacted diagnostics and structured details; unknown engine/database failures remain generic

  • selection_coverage.chain_complete confirms the canvas holds a complete source retrieval chain; it does not establish which tables the SQL uses or override truncated. Query continuations retain the original coverage snapshot


sdwis_dataframe_drop tool

  • Required canvas_id and exact table_name; requires CANVAS_PROVIDER_TYPE=duckdb and SDWIS_DATAFRAME_DROP_ENABLED=true

  • Idempotent: missing tables or expired canvases return dropped:false; other staged partitions remain available

Features

Built on @cyanheads/mcp-ts-core: stdio and Streamable HTTP transports, pluggable auth (none / jwt / oauth), swappable storage (in-memory, filesystem, Supabase, Cloudflare KV/R2/D1), structured logging with optional OpenTelemetry tracing.

EPA-specific:

  • Keyless SDWIS reads over EPA DMAP, paced at one request per second, with every returned row rechecked against the requested predicates

  • Contact-free inventory and service membership; source codes kept alongside EPA dictionary labels, which stay null when EPA has none

  • Quarterly SDWIS records, LCR summaries, and limited-participation UCMR 5 monitoring kept distinct; empty results establish neither current compliance, tap-water safety, nor contaminant absence

  • UCMR 5 archive downloaded and indexed once per published revision on first use; censored results keep a null value with the reporting limit

Agent-friendly output:

  • Provenance — effective_filters, source URL, retrieved_at, publication/HTTP validators when available, and interpretation caveats; source dates keep their calendar day, with non-midnight timestamps in a _raw field

  • Completeness — source_complete:false can stay false with has_more:false once earlier rows went to other pages or partitions; aggregation does not restore it

  • Source coverage — selection_partition identifies a retrieval and its delivered partition; canvas selection_coverage distinguishes a fully staged chain from missing, dropped, or expired partitions and companions

  • Whole-record paging — every limit defaults to 10 with a cap of 500. Ready pages return the requested number of available whole rows; bounded source work can checkpoint earlier. Follow next_cursor with unchanged selectors, including empty phase:membership pages; source cursors expire after 15 idle minutes

  • Lossless output — content[] and structuredContent carry the same values, including large rows. Byte size does not shorten pages. SDWIS_CLAMP_LIMITS=true clamps over-cap requests with a notice, log entry and counter increment; false advertises and enforces a strict maximum of 500

Getting started

No EPA account or API key is required. Add the server to Claude Code:

claude mcp add epa-drinking-water-mcp-server -- npx -y @cyanheads/epa-drinking-water-mcp-server

For other MCP clients, add this stdio configuration:

{
  "mcpServers": {
    "epa-drinking-water-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/epa-drinking-water-mcp-server"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio"
      }
    }
  }
}

For SQL staging, add "CANVAS_PROVIDER_TYPE": "duckdb" to env (Docker: -e CANVAS_PROVIDER_TYPE=duckdb), call a source tool with stage:true, and pass the returned dataset.canvas_id to sdwis_dataframe_describe and sdwis_dataframe_query. The Claude Desktop bundle fixes CANVAS_PROVIDER_TYPE=none; staging there returns canvas_disabled.

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

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

Prerequisites

  • Bun v1.4.0 or higher (or Node.js v24+).

  • Network access to data.epa.gov and www.epa.gov; allow a 180-second client timeout for the first UCMR call, which downloads and indexes the archive.

Installation

  1. Clone the repository:

git clone https://github.com/cyanheads/epa-drinking-water-mcp-server.git
  1. Navigate into the directory:

cd epa-drinking-water-mcp-server
  1. Install dependencies:

bun install
  1. Configure environment (optional):

cp .env.example .env
# set CANVAS_PROVIDER_TYPE=duckdb to enable SQL staging

Configuration

Variable

Description

Default

SDWIS_CLAMP_LIMITS

Clamp limit above 500 with a notice; false advertises and enforces a strict maximum

true

SDWIS_DATAFRAME_DROP_ENABLED

Enable early removal of staged tables when canvas is enabled

false

CANVAS_PROVIDER_TYPE

none or duckdb; npm/Docker supports DuckDB, MCPB fixes none

none

CANVAS_DEFAULT_ROW_LIMIT

SQL row ceiling, bounded by server maximum 25,000

10000

CANVAS_DEFAULT_MEMORY_LIMIT_MB

Per-engine budget, at most 512 MiB

512

MCP_TRANSPORT_TYPE

stdio or http

stdio

MCP_HTTP_HOST

HTTP bind address; Docker binds 0.0.0.0

127.0.0.1

MCP_HTTP_PORT

HTTP port

3010

MCP_AUTH_MODE

none, jwt, or oauth

none

MCP_LOG_LEVEL

Minimum log level

info

OTEL_ENABLED

Enable OpenTelemetry

false

See .env.example for the full overrides.

Running the server

Local development

bun run rebuild
bun run start:stdio
# or bun run start:http
bun run devcheck
bun run test

Docker

docker build -t epa-drinking-water-mcp-server .
docker run --rm -p 3010:3010 epa-drinking-water-mcp-server

The image defaults to Streamable HTTP on port 3010 with stateless sessions. Add -e CANVAS_PROVIDER_TYPE=duckdb for SQL staging.

Project structure

Path

Purpose

src/index.ts

Registration, source initialization, and optional canvas

src/config

Paging clamp and dataframe-drop configuration

src/domain

Selectors, reference data, schemas, and dual-surface formatting

src/mcp-server/tools/definitions

Six EPA tools and three optional dataframe tools

src/services/sdwis

Validated DMAP reads, membership, paging, and joins

src/services/ucmr5

Archive acquisition, parsing, indexing, and occurrence

src/services/dataframe

Capability-scoped staging, SQL, expiry, and removal

tests

Domain, service, tool, and integration tests

scripts

Build, checks, packaging, and release tooling

skills/epa-drinking-water-guide

Published caller workflow guide, also served over MCP

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 logging; source results never go to ctx.state or user storage

  • Register new tools in the createApp() array in src/index.ts

  • Wrap external API calls: validate raw → normalize to domain type → return output schema; never fabricate missing fields, and never infer compliance, household exposure, or exceedances

Contributing

Issues are welcome. Run checks and tests before submitting:

bun run devcheck
bun run test

License

This project is licensed under the Apache 2.0 License. See the LICENSE file for details.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables running read-only SQL queries and exploring DuckDB databases through MCP tools like listing tables, describing schemas, and fetching paginated data.
      -
    • A
      license
      A
      quality
      D
      maintenance
      Enables read-only SQL querying and exploration of data files (CSV, Parquet, JSON, Excel, etc.) via DuckDB, supporting local paths, globs, URLs, and S3 buckets.
      5
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Read-only SQL across PostgreSQL, MySQL, S3-compatible buckets and folders of Parquet, CSV and JSON files — and one query can join across all of them, federated in-process by DuckDB. Sources are given as connection strings at startup, and no tool writes: they are absent rather than disabled.
      2
      24
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables querying, sampling, and exporting datasets from over twenty keyless free public data sources spanning the EU, Switzerland, Germany, the US, and global providers through one uniform set of tools. A single consistent interface lets users list databases and tables, inspect schemas and query guides, run queries, and export results as CSV or JSON without per-API clients.
      Apache 2.0