# PurpleAir MCP

> PurpleAir connects your AI agent to one of the world’s largest air quality datasets. It monitors PM2.5, temperature, and humidity from over 50,000 sensors globally. You can check real-time conditions near an address, track wildfire smoke spikes, or pull historical data for compliance reports—all through natural conversation.

## Overview
- **Category:** iot-hardware
- **Price:** Free
- **Tags:** air-quality, environmental-monitoring, pollution-data, sensor-network, real-time-data, climate-data

## Description

This server connects your AI agent directly to PurpleAir's network—one of the biggest datasets for hyperlocal air quality. You get real-time metrics like PM2.5, temperature, and humidity from over fifty thousand sensors globally. It lets you check what's going on with air quality near any address or coordinate.

**Getting Current Air Quality Reads**

If you need to know the current status at a specific spot, `get_sensor_data` pulls the latest metrics (PM2.5, temp, etc.) from one single sensor location. You can narrow that search down even further; use `get_pm25_sensors` if you only care about PM2.5 concentrations for health monitoring. For indoor checks—like verifying air quality in a home or office—you'll run `get_indoor_sensors`. If you need to check ambient outdoor conditions across an area, `get_outdoor_sensors` grabs the current readings from those regional stations. When you know the exact sensor index number, `get_sensors_by_index` gives you fresh data without having to locate it first.

**Mapping and Locating Sensors**

You don't always know where the air quality issue is; sometimes you just need to find a monitor. To pinpoint the closest working PurpleAir sensor to a GPS coordinate, run `get_sensors_near_me`. This lists all active monitors nearby, sorted by how close they are. If you’re doing city-wide mapping projects and know two opposing corners of an area, use `get_sensors_by_bounding_box` to find every single sensor operating within that defined geographic box. For general metadata about the whole network—like filtering all sensors by type or checking their last update time—you'll use `list_sensors`.

**Deep Dive & Historical Analysis**

For compliance reports or tracking pollution spikes, you need history. `get_sensor_history` pulls a time-series log for any field you specify (like PM2.5 or humidity) over a defined date range and regular interval. If your client needs to dump that data straight into Excel or Google Sheets, use `get_sensor_history_csv`. This function grabs the exact same historical measurements but formats them as CSV text, making it ready for immediate spreadsheet analysis. You can also get current readings from multiple sensors when you know their unique index numbers using `get_sensors_by_index`.

When you combine these tools—say, checking a bounding box to find all sensors, then running `get_sensor_data` on three of them, and finally pulling a 72-hour CSV history for the worst reading—your agent handles the whole process through natural conversation. It's pure data access.

## Tools

### get_indoor_sensors
Lists all sensors measuring air quality inside buildings, homes, or enclosed spaces for indoor health checks.

### get_outdoor_sensors
Retrieves current readings (PM2.5, temp, humidity) from ambient outdoor sensors across a region.

### get_pm25_sensors
Finds and returns data only from sensors specifically measuring PM2.5 concentrations for health monitoring.

### get_sensor_data
Gets the current air quality metrics (PM2.5, temp, etc.) from a single, specific PurpleAir sensor location.

### get_sensor_history
Pulls time-series data for any requested field (PM2.5, humidity) at regular intervals over a defined time range.

### get_sensor_history_csv
Retrieves the same historical air quality measurements as `get_sensor_history`, but outputs them in CSV format.

### get_sensors_by_bounding_box
Returns all active sensors located within a defined geographic box, useful for city-wide mapping projects.

### get_sensors_by_index
Gets fresh readings for specific sensors when you already know their unique index numbers.

### get_sensors_near_me
Identifies and lists the nearest PurpleAir monitors to a given GPS coordinate, sorted by proximity.

### list_sensors
Provides metadata about sensors, allowing you to filter the entire network by type or update time.

## Prompt Examples

**Prompt:** 
```
What's the air quality near San Francisco right now?
```

**Response:** 
```
I found 23 outdoor sensors in the San Francisco area. Current PM2.5 readings range from 3.2 to 18.7 µg/m³, with an average of 8.4 µg/m³ — Moderate air quality. The highest reading is in the Bayview district. Here are the sensor locations and readings.
```

**Prompt:** 
```
Show me the PM2.5 trend for sensor 12345 over the last 24 hours.
```

**Response:** 
```
I retrieved hourly PM2.5 data for sensor 12345 over the past 24 hours. PM2.5 started at 5.1 µg/m³, peaked at 42.3 µg/m³ at 2pm (likely wildfire smoke), and has been decreasing to 12.8 µg/m³ currently. Here's the full time series.
```

**Prompt:** 
```
Find all outdoor sensors in Los Angeles and show me their PM2.5 readings.
```

**Response:** 
```
I found 47 outdoor sensors in the Los Angeles area. PM2.5 readings range from 4.1 to 35.6 µg/m³. Areas near freeways show higher readings (15-35 µg/m³) while coastal areas are cleaner (4-8 µg/m³). Here's the complete map with readings.
```

## Capabilities

### Get Real-Time Data by Location
You query the current PM2.5, temperature, humidity, and other metrics from a single sensor at a known coordinate.

### Track Historical Trends (CSV Export)
The agent retrieves time-series data over custom date ranges and formats it as CSV for immediate spreadsheet analysis.

### Map Sensors by Geographic Area
You define a bounding box (two opposing corners) to find every sensor operating within that city section or neighborhood.

### Filter by Sensor Type
You narrow the search to only indoor monitors (`get_indoor_sensors`) or only outdoor ambient stations (`get_outdoor_sensors`).

### Determine Nearby Monitors
The agent pinpoints and returns all active PurpleAir sensors closest to a specific GPS address.

## Use Cases

### Assessing Wildfire Smoke Impact
A public health official needs to know how smoke from a distant wildfire is affecting their community. They ask their agent, which uses `get_sensors_by_bounding_box` to map all local sensors, then runs `get_pm25_sensors` across the entire area. The result pinpoints elevated PM2.5 readings in specific neighborhoods.

### Optimizing Office HVAC
A facility manager wants to prove that their new filtration system works. They use `get_indoor_sensors` to get baseline data, then run `get_sensor_history` for the same location after installation. Comparing the two time series validates the investment.

### Real Estate Due Diligence
A developer needs air quality reports for a large plot of land before buying it. They use `get_sensors_by_bounding_box` to pull data across the entire property boundary, giving them a clear pollution profile that informs their risk assessment.

### Emergency Response Coordination
A wildfire response team needs immediate visibility on smoke movement. They use `get_sensors_near_me` from their current location and filter by outdoor sensors (`get_outdoor_sensors`) to guide ground crews quickly.

## Benefits

- You get granular data using `get_sensor_data` and `get_pm25_sensors`. Instead of just knowing the general area is polluted, you know *exactly* which specific sensor reading caused the alert. This level of detail matters for compliance reporting.
- Analyzing trends gets much easier with `get_sensor_history` and `get_sensor_history_csv`. You don't have to export data manually into Excel; your agent handles the time-series pull, giving you clean CSV files instantly for charting.
- Mapping out pollution sources is faster using `get_sensors_by_bounding_box`. Instead of running multiple searches, you define a corner and get every active sensor in that whole area at once. Great for city planning.
- You can separate indoor data from outdoor data by calling specialized tools like `get_indoor_sensors` or `get_outdoor_sensors`. This distinction is vital when comparing building air quality to ambient pollution levels.
- If you're on-site and need the nearest reading, use `get_sensors_near_me`. It cuts out the guesswork of finding a monitor—it just points you to the closest one.

## How It Works

The bottom line is: Instead of running multiple API calls manually, you just ask the question, and the AI handles all the necessary sensor lookups and data formatting.

1. First, you tell your AI client what kind of data you need (e.g., 'PM2.5 history for the last week').
2. Second, the agent selects and runs the right tool—maybe `get_sensor_history` or `get_sensors_by_bounding_box`—using parameters like timestamps or coordinates.
3. Finally, you get structured data (JSON or CSV) back, which your agent summarizes into plain English insights.

## Frequently Asked Questions

**How do I check air quality for a whole city with PurpleAir MCP Server?**
Use the `get_sensors_by_bounding_box` tool. You provide the northwest and southeast coordinates, and it returns current readings from every sensor within that defined area.

**Can I get historical data in CSV format using PurpleAir MCP Server?**
Yes, use `get_sensor_history_csv`. This tool pulls time-series metrics (PM2.5, temperature) over a specific date range and formats the output directly into CSV for spreadsheet analysis.

**Which tool should I use if I only care about PM2.5 levels?**
Use `get_pm25_sensors`. This tool is specialized; it filters all available sensors and returns data exclusively focused on the critical PM2.5 concentration, simplifying your query.

**What if I only want to check air quality inside a building?**
You need `get_indoor_sensors`. This tool isolates measurements from enclosed spaces, giving you crucial data for HVAC optimization and assessing workplace health risks.

**What do I need to know about using `list_sensors` for metadata retrieval?**
The `list_sensors` tool lets you pull basic sensor information and location details without fetching real-time pollution readings. You must use the `fields` parameter to specify exactly which data points (like name, latitude, or longitude) you want returned. This keeps your requests clean and efficient.

**When using `get_sensor_history`, how do I calculate averages for a specific time range?**
You control the aggregation level with the `average` parameter, which takes an integer representing seconds. For example, to get hourly averages, you pass 3600; for daily averages, use 86400. Remember to pair this with your start and end Unix timestamps.

**What coordinate format does `get_sensors_by_bounding_box` require?**
The tool requires two pairs of coordinates: the Northwest (nwlat, nwlng) corner and the Southeast (selat, selng) corner. You must ensure your latitude/longitude values are correct for both points to successfully define the entire search area.

**What core metrics can I expect when using `get_outdoor_sensors`?**
This tool consistently returns current PM2.5, temperature, and humidity readings for every outdoor sensor it finds. It's reliable for immediate air quality checks across a region, making it ideal for tracking daily pollution changes.

**How do I find air quality near my address?**
Use the `get_sensors_near_me` tool with your latitude and longitude. Alternatively, search for sensors by bounding box using `get_sensors_by_bounding_box` with corner coordinates. The API will return nearby sensors with current PM2.5, temperature, and humidity readings.

**Can I get historical air quality data?**
Yes. Use `get_sensor_history` with a sensor index and time range (Unix timestamps). You can specify which fields to retrieve (PM2.5, temperature, humidity) and set an averaging interval (e.g. 3600 for hourly averages). For spreadsheet analysis, use `get_sensor_history_csv` to get data in CSV format.

**What does PM2.5 mean and why is it important?**
PM2.5 refers to fine particulate matter smaller than 2.5 micrometers — about 30 times smaller than a human hair. These particles can penetrate deep into lungs and enter the bloodstream, causing respiratory and cardiovascular health effects. The WHO guideline is 5 µg/m³ annual average. PurpleAir sensors measure PM2.5 in real-time, making them essential for health advisories and pollution monitoring.