epa-mcp-server

---

概述

涵盖五个联邦计划的 EPA 环境数据——设施合规情况（ECHO）、有毒物质排放（TRI）、Superfund 场址、饮用水系统（SDWIS）和环境正义筛查（EJScreen）——以及 AirNow 实时空气质量。获取设施的检查和执法记录、追踪某个地区的有毒物质排放，或筛查任意地点的环境正义风险。

工具

工具	描述
epa_echo_search_facilities	按地点、环境计划或合规状态搜索受 EPA 监管的设施，涵盖 CAA、CWA、RCRA、TRI 和 SDWA
epa_echo_get_facility	根据 EPA Registry ID 获取单个设施的完整合规档案，包括合规状态、检查、执法行动、罚款和 TRI ID
epa_echo_search_violations	按州、计划或日期范围搜索 EPA 民事和刑事执法案件
epa_airnow_get_conditions	获取 AirNow 当前 AQI 观测值或已发布的 AQI 预报
epa_tri_get_facility_releases	获取单个设施按化学品划分的有毒物质排放清单数据
epa_tri_search_releases	搜索某个州或县各设施的有毒物质排放清单记录
epa_superfund_search_sites	按地点或 NPL 列入状态搜索 Superfund（CERCLA/SEMS）场址
epa_water_search_systems	按州或 ZIP 代码搜索饮用水系统（SDWIS）
epa_ejscreen_get_scores	获取某个地点及其缓冲区的 EJScreen 环境正义指标

资源

资源	描述
epa://facility/{registry_id}	按 EPA Registry ID 查询设施的完整合规档案（数据与 epa_echo_get_facility 相同）
epa://superfund/{site_id}	按 SEMS 场地 ID 查询 Superfund 场地记录

也可以通过工具访问所有资源数据——在仅支持工具的 MCP 客户端中，使用 epa_echo_get_facility 和 epa_superfund_search_sites 进行程序化访问。

能力参考

epa_echo_search_facilities _工具

• 提供 ZIP 邮政编码、州、城市（前缀匹配，最好同时提供州），或纬度 + 经度 + radius_miles（最大 100 英里）；最多返回 100 条结果（默认 50 条）
• 返回供 epa_echo_get_facility 使用的 registryId、县和 fipsCode、坐标、各项目标志，以及五年内的检查和处罚总数
• programs 可取 CAA、CWA、RCRA、TRI 或 SDWA；has_violation 会筛出存在重大违规的设施；active_only 会筛出持有有效许可证的设施

---

epa_echo_get_facility _工具

• registry_id 来自 epa_echo_search_facilities
• 返回 complianceStatus、按法规划分的 programCompliance 摘要、最近五年的最新 100 次检查（inspectionsTotal 统计全部检查）、五年的执法行动及处罚、最新 TRI 总量及 triReleasesTransfersYear，以及供 epa_tri_get_facility_releases 使用的 triFacilityIds
• 如果状态查询失败，档案中不会返回 complianceStatus，并会通过 notice 说明；未知 ID 会报错 facility_not_found

---

epa_echo_search_violations _工具

• 需要提供 state 或 zip_code；最多返回 100 个案件（默认 50 个）
• program 可筛选 CAA、CWA、RCRA、SDWA、CERCLA、FIFRA 或 TSCA，匹配案件引用的任何法律；case_type 可取 civil、criminal 或 all（默认值）
• date_filed_start / date_filed_end（YYYY-MM-DD，包含起止日期）限定立案日期。只有民事案件带有立案日期，因此指定日期时，all 会返回民事案件并附带 notice，而 criminal 会被拒绝

---

epa_airnow_get_conditions _工具

• 提供 zip_code，或同时提供 latitude 和 longitude；mode 可取 current（默认值）或 forecast
• current 模式会返回 50 英里范围内最近监测站的各污染物最新小时 NowCast AQI；forecast 模式会返回每个已发布日期及其 dateValid、actionDay 和 discussion，而 forecast_date（YYYY-MM-DD）可限定为一天
• 读数包含 categoryName 和 categoryNumber（1 为良好，6 为危险）；attribution 表示数据为初步数据，不适用于监管或执法决策
• 仅当设置了 AIRNOW_API_KEY 时才会注册；响应会缓存约一小时

---

epa_tri_get_facility_releases _工具

• facility_id 是来自 epa_tri_search_releases 或 epa_echo_get_facility 的 triFacilityIds 的 TRI facilityId；可选参数包括 year（1987–2030）和部分 chemical_name
• 按化学物质返回空气、水、土地和地下灌注排放量，以及一次性／非例行总量；省略 year 时按报告年份从新到旧排列。达到 500 条申报记录时，两个响应界面都会提示可能还有更多记录；可用 year 或 chemical_name 缩小范围
• 数量单位为磅；以克报告的二噁英记录会转换单位，并带有 reportedUnit: "grams"

---

epa_tri_search_releases _工具

• 需要 2 个字母的 state；可选参数包括 county（不区分大小写的部分匹配）、部分 chemical_name 和 year；最多返回 200 条记录（默认 50 条），省略 year 时按报告年份从新到旧排列
• 返回供 epa_tri_get_facility_releases 使用的 facilityId，以及每条记录的一次性／非例行总量；include_release_breakdown: true 会额外返回空气、水、土地和地下灌注排放量，但会多发起一次上游请求（EPA 尚未缓存数据时最多约需 20 秒）
• 以克报告的二噁英记录会转换为磅，并带有 reportedUnit: "grams"

---

epa_superfund_search_sites _工具

• 提供 state/city/zip_code，或 latitude + longitude + radius_miles（0.1–500）；最多返回 200 个站点（默认 50 个）
• 返回站点标识符、位置、NPL 和清理状态；npl_status 可筛选已列入、未列入、拟列入或全部（默认）
• 邻近搜索会遍历所有包含纬度/经度的候选项，应用精确距离计算，并优先返回最近的站点。notice 会说明结果上限排除了多少个匹配站点；没有坐标的站点无法定位。所有候选项页面共用 50 秒的时限——如果超时，请缩小半径或添加筛选条件

---

epa_water_search_systems _工具

• 必须提供 state 或 zip_code；最多返回 200 个供水系统（默认 50 个）。zip_code 匹配的是每个系统登记地址，而非其服务区域
• has_violation 仅保留存在未结 SDWIS 违规记录的系统；pws_type 可设为 community、non-transient 或 transient，并在 type 中分别返回为 CWS / NTNCWS / TNCWS
• has_violation 最多读取 1,000 条记录；达到上限时，notice 会说明列表可能遗漏存在违规记录的系统

---

epa_ejscreen_get_scores _工具

• 必须提供 latitude 和 longitude；distance 默认为 1，unit 默认为英里（也接受公里）；缓冲区上限为 15 英里
• 返回 13 项环境指标和 6 项人口统计指标，包含全国/州百分位数和人口统计指数；若位置超出覆盖范围，coverage.valid: false 会附带说明
• EJScreen v2.2 (2022) 数据来自社区维护的 EJAM API（Public Environmental Data Partners）

---

epa://facility/{registry_id} _资源

• registry_id 来自 epa_echo_search_facilities
• 返回 epa_echo_get_facility 合规概况；找不到对应设施时会报错

---

epa://superfund/{site_id} _资源

• site_id 来自 epa_superfund_search_sites
• 返回 Superfund 站点记录；找不到对应 SEMS 记录时会报错

功能

基于 @cyanheads/mcp-ts-core 构建：支持 stdio 和 Streamable HTTP 传输、可插拔身份验证（none / jwt / oauth）、可替换存储（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1），以及支持可选 OpenTelemetry 跟踪的结构化日志记录。

EPA 专属功能：

• 通过一套 epa_ 工具提供 ECHO（设施合规）、Envirofacts DMAP（TRI、Superfund、SDWIS）、AirNow（空气质量）和社区维护的 EJAM API（EJScreen v2.2，2022）功能
• AirNow 响应会缓存约一小时，以遵守每个密钥的速率限制
• TRI 报告约滞后 18 个月；最新报告年份通常比当前年份早两年

便于 Agent 使用的输出：

• 搜索结果会包含后续工具所需的 ID：registryId、fipsCode、facilityId 和 triFacilityIds
• 如果状态查询失败，epa_echo_get_facility 会返回部分概况并附带 notice
• 搜索结果为空时，会返回 message，其中回显已应用的筛选条件，并建议如何放宽条件

入门

公共托管实例

公共实例位于 https://epa.caseyjhand.com/mcp，无需安装。该实例未配置 AirNow 密钥，因此无法使用 epa_airnow_get_conditions；其余 8 个工具均可使用。通过 Streamable HTTP 将任意 MCP 客户端指向该实例：

{
  "mcpServers": {
    "epa-mcp-server": {
      "type": "streamable-http",
      "url": "https://epa.caseyjhand.com/mcp"
    }
  }
}

自托管 / 本地运行

将以下内容添加到 MCP 客户端配置文件中。AirNow API 密钥为可选项——设置 AIRNOW_API_KEY 即可启用 epa_airnow_get_conditions（可在 docs.airnowapi.org 免费注册）；未设置密钥时，服务仍会启动并提供其余 8 个工具。ECHO、DMAP 和 EJScreen 工具无需身份验证即可使用。

{
  "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"
      }
    }
  }
}

也可以使用 npx（无需 Bun）：

{
  "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"
      }
    }
  }
}

或使用 Docker：

{
  "mcpServers": {
    "epa-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "-e", "AIRNOW_API_KEY=your-airnow-key",
        "ghcr.io/cyanheads/epa-mcp-server:latest"
      ]
    }
  }
}

如需使用 Streamable HTTP，请设置传输方式并启动服务：

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

前置条件

• Bun v1.4.0 或更高版本（或 Node.js v24+）；开发和 Docker 使用 Bun v1.4.4。
• （可选）AirNow API 密钥，用于启用 epa_airnow_get_conditions — 可在 docs.airnowapi.org/account/request 免费注册。没有密钥时，服务仍可运行其他 8 个工具。ECHO、DMAP 和 EJScreen 工具无需 API 密钥。

安装

1. 克隆仓库：

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

2. 进入目录：

cd epa-mcp-server

3. 安装依赖项：

bun install

4. 配置环境：

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

配置

所有配置都会在启动时通过 src/config/ 中的 Zod 架构进行验证。主要环境变量：

变量	描述	默认值
AIRNOW_API_KEY	**可选。**启用 epa_airnow_get_conditions。	—
EPA_ECHO_BASE_URL	ECHO API 基础 URL	https://echodata.epa.gov/echo
EPA_DMAP_BASE_URL	Envirofacts DMAP API 基础 URL	https://data.epa.gov/dmapservice
EPA_AIRNOW_BASE_URL	AirNow API 基础 URL	https://www.airnowapi.org/aq
EJSCREEN_API_BASE_URL	EJScreen (EJAM) API 基础 URL	https://api.ejanalysis.com
MCP_TRANSPORT_TYPE	传输方式：stdio 或 http	stdio
MCP_HTTP_PORT	HTTP 服务端口	3010
MCP_HTTP_ENDPOINT_PATH	HTTP 端点路径	/mcp
MCP_SESSION_MODE	HTTP 会话：auto、stateful 或 stateless	stateless
MCP_AUTH_MODE	身份验证模式：none、jwt 或 oauth	none
MCP_LOG_LEVEL	日志级别（RFC 5424）	info
LOG_TOOL_FAILURE_PAYLOADS	记录失败调用的参数和结果，并对键名进行脱敏。自由格式值中的密钥仍会显示。	false
LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES	每条日志负载的字节上限	16384
LOGS_DIR	日志文件目录（仅限 Node.js）	<project-root>/logs
STORAGE_PROVIDER_TYPE	存储后端：in-memory、filesystem、supabase、cloudflare-kv/r2/d1	in-memory
OTEL_ENABLED	启用 OpenTelemetry 链路追踪和指标	false
OTEL_EXPORTER_OTLP_ENDPOINT	OTLP 基础 URL	—
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT / OTEL_EXPORTER_OTLP_METRICS_ENDPOINT	各信号的端点覆盖值	—
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT	启用 OTLP 日志导出	—

完整的可选覆盖项列表请参阅 .env.example。

运行服务

本地开发

• 构建并运行：

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

• 运行检查和测试：

  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

Dockerfile 默认使用 HTTP 传输、无状态会话模式，并将日志写入 /var/log/epa-mcp-server。默认会安装 OpenTelemetry 对等依赖项 — 构建时使用 --build-arg OTEL_ENABLED=false 可省略这些依赖项。

项目结构

目录	用途
src/index.ts	createApp() 入口 — 注册工具/资源并初始化服务。
src/config	使用 Zod 解析并验证服务专属环境变量。
src/mcp-server/tools	工具定义（*.tool.ts）。包含 ECHO、DMAP、EJAM 和 AirNow 的 9 个工具。
src/mcp-server/resources	资源定义（*.resource.ts）。设施和 Superfund URI 处理程序。
src/services/echo	ECHO REST API 服务层 — 设施搜索、设施详情、执法案件。
src/services/dmap	Envirofacts DMAP 服务层 — TRI 排放、Superfund 场址、饮用水系统。
src/services/airnow	AirNow 服务层 — 当前和预测 AQI 观测数据。
src/services/ejscreen	EJScreen (EJAM) 服务层 — 点位及缓冲区的环境正义指标。
tests/	与 src/ 结构对应的单元测试和集成测试。

开发指南

开发指南和架构规则请参阅 CLAUDE.md。简要说明如下：

• 由处理器抛出异常，框架负责捕获——工具逻辑中不要使用 try/catch
• 使用 ctx.log 记录请求范围的日志，使用 ctx.state 存储租户范围的数据
• 通过 src/mcp-server/*/definitions/index.ts 中的汇总文件注册新工具和资源
• 封装外部 API 调用：先验证原始数据，再规范化为领域类型，最后返回输出架构；绝不捏造缺失字段
• ECHO 搜索必须至少指定一个地理参数——不指定范围的查询会在调用实时 API 时超时

贡献

欢迎提交问题。提交前请运行检查和测试：

bun run devcheck
bun run test

许可证

Apache-2.0——详情请参阅 LICENSE。