nepa-mcp

Federal environmental data and regulatory research for AI-assisted NEPA workflows

Works with

Built with

NEPA MCP is the Model Context Protocol (MCP) server layer of the PermitAI
toolkit. It gives AI agents structured access to federal environmental,
regulatory, biological, cultural, socioeconomic, and jurisdictional data used
in NEPA screening and permitting research.

The current inventory includes 19 MCP servers, 46 MCP tools, and 32 GIS
layers. Together, the tools and layers represent 78 environmental and
regulatory research capabilities. These capabilities draw on public data
from 12 federal agencies, along with interagency and nonfederal sources.

The MCP Tool Catalog provides the complete server
and tool inventory. The Map Composer MCP server queries
public GIS services from eight federal data publishers at request time. It can
compose selected results into an interactive map or a provenance-rich GeoJSON
export.

Important

NEPA MCP is a screening and research aid. It does not make legal or agency
determinations, replace consultation with agencies or Tribes, or guarantee
that an upstream dataset is complete or current. Confirm material findings
against authoritative records and current requirements.

Quick Start

Prerequisites

• Python 3.12 or newer
• pipx for an isolated installation

Install the stable package from PyPI:

pipx install nepa-mcp
pipx ensurepath

If pipx ensurepath reports a change, reopen the terminal before continuing.
If pipx selects a Python version older than 3.12, repeat the installation with
pipx install --python 3.12 nepa-mcp.

Verify the installation and list the available servers:

nepa-mcp doctor
nepa-mcp list-servers

Upgrade an existing PyPI installation:

pipx upgrade nepa-mcp

If pipx upgrade keeps an older version that was originally installed from a
local checkout or Git URL, replace that pipx environment with the current PyPI
release:

pipx install --force nepa-mcp
nepa-mcp doctor

This leaves the separate per-user NEPA MCP credential file unchanged.

Configure an MCP Client

Before continuing: For Claude Code or VS Code, confirm that the terminal
is open in the project or workspace you intend to configure. The configuration
file will be created or updated there.

Restart or reload the selected client after configuring it; for Codex, start a
new task.

Codex Plugin

The Codex plugin registers all 19 servers and includes the nepa-screening
skill. If you use the plugin, do not also run nepa-mcp configure codex.

Install and verify the Python runtime before adding the plugin:

pipx install nepa-mcp
nepa-mcp doctor

doctor should report Installed servers: 19. Then add the marketplace in
Codex Desktop:

1. Open Plugins and select Add plugin marketplace.
2. Enter pnnl/nepa-mcp for Source and v0.1.1 for Git ref.
3. Leave Sparse paths blank, then select Add marketplace.
4. Install NEPA-MCP from the NEPA-MCP Local marketplace.

The equivalent Codex CLI commands are:

codex plugin marketplace add pnnl/nepa-mcp --ref v0.1.1
codex plugin add nepa-mcp@nepa-mcp-local

Start a new Codex task after installing the plugin so the new MCP tools and
skill are loaded.

Map Composer

map_composer turns project-area data into an interactive HTML map or a
combined GeoJSON file for QGIS, ArcGIS, and other geospatial workflows. It
provides 32 selectable overlays assembled at request time from Census, USFWS,
USACE, USGS, BLM, USFS, NPS, and NIFC public GIS services.

The result is intentionally interactive rather than a fixed stack: start with
one of five profiles, then toggle returned layers to preserve visual clarity
for the question at hand. Every map reports requested, rendered, empty,
partial, and failed layer counts so source coverage remains visible.

Chesapeake Bay watershed, 20-mile project area: 12 overlays shown from 16 returned locally in a 32-layer request, with no failed sources. The generated map keeps every returned layer independently toggleable.

See the Map Composer guide for profile membership, the
complete 32-layer catalog, output behavior, provenance, and artifact storage.

Credentials

Credentials are not required to install NEPA MCP or use the other 17 servers.
The Census and EPA AQS servers require credentials before they can return data:

Set the variables in the shell or create a private per-user credential file:

nepa-mcp configure credentials
nepa-mcp doctor

configure creates a template only when one does not already exist and prints
its location. The default is the operating system's per-user configuration
directory under nepa-mcp/credentials.env; override it with
NEPA_MCP_CONFIG_FILE. Environment variables take precedence over the file.
Credentials are not copied into MCP client or plugin configuration, and
doctor reports only whether each value is present.

Server Inventory

Many geographic servers also use Esri's ArcGIS Geometry Service
to construct ROI buffers. Esri is a supporting geometry-service provider,
not the publisher of the agency datasets identified above.

See Geographic Inputs and Data Behavior
for ROI constraints, area and clipping semantics, coverage warnings, and
partial-source behavior across geographic servers.

Development

uv is required only for source development and
testing. From the repository root:

uv sync --all-groups
uv run ruff check .
uv run ruff format --check .
uv run python -m compileall -q .
uv run pytest -q

Most tests do not require credentials. To exercise the optional Census or EPA
AQS integrations, use uv run nepa-mcp configure or export the variables
listed above. A repository .env file is not loaded automatically; opt into it
with uv run --env-file .env <command>.

Each domain follows the same basic layout:

server_name/
├── requirements.txt
├── server.py
└── src/
    ├── apis/
    └── core/

Shared runtime, HTTP, validation, and ArcGIS utilities live in
nepa_mcp_common/. The root pyproject.toml builds the installable distribution;
individual requirements.txt files remain available for standalone deployment
packaging.

Inspect a server's MCP contract with FastMCP:

uv run fastmcp inspect cfr/server.py:mcp --skip-env

The test suite checks server startup and discovery, tool-schema readability,
offline invalid-argument handling, shared utilities, and distribution contents.

Data Sources and Licensing

Source agencies and publishers: Bureau of Land Management
· Department of the Interior
· U.S. Census Bureau
· U.S. Environmental Protection Agency
· Esri
· Federal Emergency Management Agency
· Office of the Federal Register
and U.S. Government Publishing Office
· Global Biodiversity Information Facility
and contributing dataset publishers
· National Park Service
· National Interagency Fire Center
· NOAA Fisheries
· U.S. Army Corps of Engineers
· U.S. Fish and Wildlife Service
· USDA Forest Service
· U.S. Geological Survey

Note

Agency and publisher names identify upstream data provenance only. NEPA MCP
is an independent project and is not affiliated with, sponsored by, or
endorsed by these organizations.

The data-source inventory records
the source agencies, endpoints, authentication requirements, license signals,
and release notes for the current server inventory. Upstream data remains
subject to each source's terms and authoritative-use guidance.

Contributing

Issues and pull requests are welcome. See Contributing for
development setup, required checks, pull-request expectations, and DCO
sign-off. Participation is governed by the Code of Conduct.
Report suspected vulnerabilities through the private process in the
Security Policy.
See Support for the project's best-effort support boundary and
issue-reporting guidance. Current repository-governance roles are listed in
Project Roles.

Acknowledgments

This work was supported by the U.S. Department of Energy’s Office of Policy and
Office of Critical Minerals and Energy Innovation and performed at Pacific
Northwest National Laboratory.

The authors acknowledge Tracy Fuentes for NEPA input during IPaC MCP evaluation;
Weili Xu for consultation on packaging MCP servers in Codex Marketplace
plugins; Scott Spare, Derek Lilienthal, and David Kocen for discussions on MCP
deployment in cloud environments; and Anastasia Bernat for GIS perspectives
shared during project discussions.

License

The repository's source code is available under the
BSD 3-Clause License. The accompanying PNNL/DOE notice
contains the sponsorship, warranty, endorsement, and views disclaimer.

Citation

If you use NEPA MCP in research, environmental assessments, or other scientific
or technical publications, please use the metadata in CITATION.cff
or cite it as:

@software{nepa_mcp,
  author       = {Chaturvedi, Sarthak and Chintalapati, Renuka and Nally, Daniel and Parker, Mike and Munikoti, Sai and Horawalavithana, Sameera},
  title        = {PermitAI NEPA MCP Toolkit: Federal Environmental Data, Regulatory Research, and Geospatial Screening},
  year         = {2026},
  institution  = {Pacific Northwest National Laboratory},
  url          = {https://github.com/pnnl/nepa-mcp},
  version      = {0.1.1},
  license      = {BSD-3-Clause}
}