EPA Air Quality System (AQS) MCP Server

An MCP (Model Context Protocol) server that provides access to the EPA Air Quality System API. This server enables Claude and other MCP clients to query air quality data, monitor information, and quality assurance data from the EPA's comprehensive air quality database.

Features

• 31 MCP tools covering all major AQS API endpoints
• Rate limiting (5 seconds between requests) to comply with API guidelines
• Date validation (same calendar year requirement)
• Credential resolution from parameters or environment variables
• Comprehensive error handling

Installation

# Clone the repository
git clone https://github.com/yourusername/aqs-mcp.git
cd aqs-mcp

# Install dependencies
npm install

# Build the project
npm run build

Configuration

Getting an API Key

1. Use the aqs_signup tool with your email address
2. Check your email for the API key

Environment Variables (Optional)

Set these to avoid passing credentials with every request:

export AQS_EMAIL="your.email@example.com"
export AQS_API_KEY="your-api-key"

Claude Desktop Configuration

Add to your claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "aqs": {
      "command": "node",
      "args": ["/absolute/path/to/aqs-mcp/dist/index.js"],
      "env": {
        "AQS_EMAIL": "your.email@example.com",
        "AQS_API_KEY": "your-api-key"
      }
    }
  }
}

Available Tools

Authentication & Status

Tool	Description
aqs_signup	Register for an API key (sent via email)
aqs_is_available	Check if the API is operational

Reference Data (Lists)

Tool	Description
aqs_list_states	Get all US state FIPS codes
aqs_list_counties	Get counties in a state
aqs_list_sites	Get monitoring sites in a county
aqs_list_cbsas	Get Core Based Statistical Areas
aqs_list_parameter_classes	Get parameter classification groups
aqs_list_parameters	Get parameters within a class

Monitor Queries

Tool	Description
aqs_monitors_by_site	Get monitors at a specific site
aqs_monitors_by_county	Get monitors in a county
aqs_monitors_by_state	Get monitors in a state
aqs_monitors_by_box	Get monitors in a lat/lon bounding box
aqs_monitors_by_cbsa	Get monitors in a CBSA

Sample Data

Tool	Description
aqs_sample_data_by_site	Get raw sample data at a site
aqs_sample_data_by_county	Get raw sample data for a county
aqs_sample_data_by_state	Get raw sample data for a state
aqs_sample_data_by_box	Get raw sample data in a bounding box
aqs_sample_data_by_cbsa	Get raw sample data for a CBSA

Daily Summaries

Tool	Description
aqs_daily_summary_by_site	Daily summary at a site
aqs_daily_summary_by_county	Daily summary for a county
aqs_daily_summary_by_state	Daily summary for a state
aqs_daily_summary_by_box	Daily summary in a bounding box
aqs_daily_summary_by_cbsa	Daily summary for a CBSA

Quarterly Summaries

Tool	Description
aqs_quarterly_summary_by_site	Quarterly summary at a site
aqs_quarterly_summary_by_county	Quarterly summary for a county
aqs_quarterly_summary_by_state	Quarterly summary for a state

Annual Summaries

Tool	Description
aqs_annual_summary_by_site	Annual summary at a site
aqs_annual_summary_by_county	Annual summary for a county
aqs_annual_summary_by_state	Annual summary for a state
aqs_annual_summary_by_box	Annual summary in a bounding box
aqs_annual_summary_by_cbsa	Annual summary for a CBSA

Common Parameter Codes

Code	Pollutant
44201	Ozone
88101	PM2.5 Local
88502	PM2.5 FRM/FEM
81102	PM10
42401	SO2
42101	CO
42602	NO2

Location Codes

Parameter	Format	Example	Description
state	2-digit FIPS	06	California
county	3-digit FIPS	037	Los Angeles County
site	4-digit	0001	Site number
cbsa	5-digit	31080	LA Metro Area

Date Format

All dates use YYYYMMDD format (e.g., 20240101 for January 1, 2024).

Important: Begin and end dates must be in the same calendar year.

Example Usage

Query daily ozone data for Los Angeles County in January 2024:

{
  "name": "aqs_daily_summary_by_county",
  "arguments": {
    "state": "06",
    "county": "037",
    "param": "44201",
    "bdate": "20240101",
    "edate": "20240131"
  }
}

Testing

Test with the MCP Inspector:

npx @modelcontextprotocol/inspector node dist/index.js

API Constraints

• Rate Limit: 10 requests per minute (server enforces 5-second delay)
• Max Parameters: 5 parameter codes per request
• Date Range: Must be within same calendar year
• Data Volume: Large queries may timeout; use smaller date ranges

Development

# Watch mode
npm run dev

# Build
npm run build

# Run directly
node dist/index.js

License

MIT

Links

• EPA AQS API Documentation
• MCP Specification