EPA Envirofacts MCP Server
A Model Context Protocol (MCP) server that provides AI agents with structured access to U.S. EPA environmental data through the Envirofacts API.
Features • Installation • Usage • Configuration • Contributing
Features
Environmental Summary by Location: Get comprehensive environmental data for any U.S. location including:
Nearby regulated facilities (TRI, RCRA, SDWIS, FRS)
Chemical release data from Toxics Release Inventory
Safe Drinking Water Act violations
Hazardous waste sites
Distance-based ranking and filtering
Geocoding Support: Convert addresses, cities, and ZIP codes to coordinates
Robust Error Handling: Retry logic, timeout handling, and graceful degradation
Modular Architecture: Easy to extend with additional EPA data tools
Comprehensive Testing: Unit tests with mocks and integration tests with live API
Installation
Quick Start (Recommended)
Install using uv (fastest method):
Alternative: Traditional Installation
Prerequisites:
Python 3.11 or higher
pip (Python package manager)
Steps:
Using with Claude Desktop or Other MCP Clients
Add this configuration to your MCP client settings (e.g., claude_desktop_config.json
):
Or with traditional installation:
Configuration (Optional)
Create a .env
file for custom settings:
Configuration
The server can be configured through environment variables or a .env
file:
Configuration Options
EPA_API_BASE_URL
: Base URL for EPA Envirofacts API (default: https://data.epa.gov/efservice/)REQUEST_TIMEOUT
: Request timeout in seconds (default: 300)RETRY_ATTEMPTS
: Number of retry attempts for failed requests (default: 3)MAX_RESULTS_PER_QUERY
: Maximum results per API query (default: 1000)GEOCODING_SERVICE
: Geocoding service to use (default: nominatim)GEOCODING_USER_AGENT
: User agent string for geocoding requestsLOG_LEVEL
: Logging level (DEBUG, INFO, WARNING, ERROR)
Usage
Running the Server
With uv (Recommended)
Traditional Method
The server will start and register the available tools. You can then connect to it using an MCP client (like Claude Desktop).
Connecting to Claude Desktop
Open your Claude Desktop configuration file:
macOS:
~/Library/Application Support/Claude/claude_desktop_config.json
Windows:
%APPDATA%\Claude\claude_desktop_config.json
Add the EPA Envirofacts MCP server:
Restart Claude Desktop
Look for the 🔌 icon to confirm the server is connected
Available Tools
1. Environmental Summary by Location
Get comprehensive environmental data for any U.S. location.
Parameters:
location
(string): Address, city, or ZIP code (e.g., "New York, NY", "10001", "Los Angeles, CA")radius_miles
(float, optional): Search radius in miles (default: 5.0, max: 100.0)
Returns:
Location coordinates and search parameters
Count of facilities by type (TRI, RCRA, SDWIS, FRS)
Top facilities ranked by distance
Water systems and active violations
Chemical release summary with top chemicals
Hazardous waste sites
Summary statistics
Example Usage:
2. Health Check
Check system health and EPA API connectivity.
Returns:
Server status and version
EPA API connectivity status
Configuration information
Example Queries
Testing
Unit Tests
Run unit tests with mocked responses:
Integration Tests
Run integration tests with live EPA API calls (slower):
Test Coverage
Generate test coverage report:
Test Categories
Unit Tests: Fast tests with mocked dependencies
Integration Tests: Slower tests with live EPA API calls (marked with
@pytest.mark.integration
)Slow Tests: Tests that may take longer (marked with
@pytest.mark.slow
)
Project Structure
EPA Data Sources
The server integrates with multiple EPA data systems:
FRS (Facility Registry Service): Master facility database
TRI (Toxics Release Inventory): Chemical release data
SDWIS (Safe Drinking Water Information System): Water quality violations
RCRA (Resource Conservation and Recovery Act): Hazardous waste sites
Error Handling
The server includes comprehensive error handling:
Network Errors: Automatic retry with exponential backoff
API Timeouts: Graceful handling of EPA API 15-minute timeout
Geocoding Failures: Clear error messages with suggestions
Empty Results: Informative messages instead of errors
Partial Failures: Continue with available data, log warnings
Performance
Parallel API Calls: Uses
asyncio.gather()
for concurrent EPA API requestsGeocoding Cache: In-memory cache to avoid repeated geocoding requests
Rate Limiting: Respects Nominatim's 1 request/second rate limit
Pagination: Limits results to prevent overwhelming responses
Distance Filtering: Efficiently filters facilities by distance
Development
Setting Up Development Environment
Running Development Server
Contributing
Fork the repository
Create a feature branch:
git checkout -b feature-name
Make your changes and add tests
Run the test suite:
uv run pytest tests/ -v
Commit your changes:
git commit -am 'Add feature'
Push to the branch:
git push origin feature-name
Submit a pull request
Adding New Tools
To add a new EPA data tool:
Create a new tool file in
src/tools/
Implement the tool function with proper error handling
Add unit tests in
tests/tools/
Add integration tests if needed
Register the tool in
server.py
Update documentation
Code Style
Follow PEP 8 style guidelines
Use type hints for all function parameters and return values
Include comprehensive docstrings
Write tests for all new functionality
Use meaningful variable and function names
Troubleshooting
Common Issues
Installation Issues:
Make sure you have Python 3.11 or higher:
python --version
If using uv, ensure it's up to date:
uv self update
Try clearing uv cache:
uv cache clean
Geocoding Failures:
Check internet connectivity
Verify location string format
Try a different location format (ZIP code vs. city name)
Rate limit: Nominatim allows 1 request/second
API Timeouts:
Reduce search radius
Check EPA API status at https://data.epa.gov/efservice/
Increase timeout in configuration
Empty Results:
Try a larger search radius
Verify location is in the United States
Check if area has EPA-regulated facilities
MCP Connection Issues:
Verify the absolute path in your MCP client configuration
Check that the server starts without errors:
uv run python server.py
Restart your MCP client (e.g., Claude Desktop)
Check client logs for connection errors
Debug Mode
Enable debug logging:
Logs Location
Server logs: Check console output
Claude Desktop logs:
macOS:
~/Library/Logs/Claude/mcp*.log
Windows:
%APPDATA%\Claude\logs\mcp*.log
What is MCP?
The Model Context Protocol (MCP) is an open protocol that enables AI assistants like Claude to securely connect to external data sources and tools. This server implements MCP to provide access to EPA environmental data.
Learn more: modelcontextprotocol.io
Available Data Sources
This server provides access to:
FRS (Facility Registry Service): Master facility database with 800,000+ facilities
TRI (Toxics Release Inventory): Chemical release data from industrial facilities
SDWIS (Safe Drinking Water Information System): Water quality and violations data
RCRA (Resource Conservation and Recovery Act): Hazardous waste sites and handlers
All data is sourced from the U.S. Environmental Protection Agency's public Envirofacts API.
License
This project is licensed under the MIT License - see the LICENSE file for details.
Acknowledgments
U.S. Environmental Protection Agency for providing the Envirofacts API
Anthropic for the Model Context Protocol
FastMCP framework for MCP server implementation
Geopy library for geocoding functionality
Astral for the uv package manager
Support
For questions, issues, or contributions:
Check the troubleshooting section above
Search existing issues in the repository
Create a new issue with detailed information
Include error messages, configuration, and steps to reproduce
Related Projects
Note: This server provides access to public EPA data. All data is publicly available through the EPA Envirofacts API. No API key is required for basic usage.
Disclaimer: This is an unofficial third-party implementation and is not affiliated with or endorsed by the U.S. Environmental Protection Agency.
remote-capable server
The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.
Provides AI agents with structured access to U.S. EPA environmental data including nearby regulated facilities, chemical releases, water violations, and hazardous waste sites for any U.S. location. Enables comprehensive environmental impact analysis through the EPA Envirofacts API with geocoding support and distance-based filtering.