nepa-mcp 0.1.0

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

Verify the installation and list the available domains:

nepa-mcp doctor
nepa-mcp list-servers

Start an individual server over stdio:

nepa-mcp server ipac
nepa-mcp server cfr

Individual servers are the recommended pattern for MCP clients. An aggregate proxy is also available for testing or workflows that deliberately want every tool behind one connection:

nepa-mcp server all

Upgrade an existing PyPI installation:

pipx upgrade nepa-mcp

Install from source

For development or unreleased changes, clone the repository and install the current checkout:

git clone https://github.com/pnnl/nepa-mcp.git
cd nepa-mcp
pipx install .

If nepa-mcp is already installed, replace it with the current checkout:

pipx install --force .

Configure an MCP Client

The repository includes examples for Claude Code (.mcp.json), VS Code (.vscode/mcp.json), and Codex (config.template.toml). Each example registers the 19 capabilities as separate MCP servers.

The CLI can merge those entries into an existing client configuration:

nepa-mcp configure claude
nepa-mcp configure vscode
nepa-mcp configure codex

Use --dry-run to preview the result or --path to choose a different file. Unrelated MCP entries are preserved, and an existing file receives a one-time .nepa-mcp.bak backup.

Codex Plugin

The repository contains a Codex marketplace and a nepa-mcp plugin. The plugin registers all 19 servers and includes the nepa-screening skill. Install the Python runtime from PyPI first, 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.0 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.0
codex plugin add nepa-mcp@nepa-mcp-local

Start a new Codex task after installing or updating 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

Most servers use public APIs without credentials. Two integrations support optional credentials:

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

nepa-mcp configure
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.0},
  license      = {BSD-3-Clause}
}