services
PurpleAir
Overview

PurpleAir Service

PurpleAir provides real-time air quality data from a network of citizen sensors. The service is Stored mode: historical data is served from the database when ingested; live data comes from the PurpleAir API.

Overview

The PurpleAir service provides access to:

  • Current sensor observations (PM2.5, temperature, humidity, etc.)
  • Sensor metadata and location
  • Sensors near a location (bounding box / radius)
  • Historical observations from the database (when data has been ingested)

Available Tools

See the Tools Reference for complete tool documentation.

Quick Example

curl -X POST \
  -H "x-api-key: dev-key-12345" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "purpleair.get_sensor_data",
      "arguments": {
        "sensor_index": "12345",
        "data_format": "cleaned"
      }
    }
  }' \
  http://localhost:3001/api/v1/services/purpleair/mcp

Data Formats

Cleaned Format (Default)

Normalized measurements with consistent units and parameter names (e.g. pm2_5_ug_per_m3, air_temperature_c). Suitable for cross-service comparison.

Raw Format

Original PurpleAir API fields (e.g. pm2_5_atm, temperature) as returned by the upstream API.

Authentication

  • API key required: Set PURPLEAIR_API_KEY in the environment (or pass via the MCP service config). The PurpleAir API requires an API key for all requests.
  • Get an API key at PurpleAir (opens in a new tab).

Data Mode

  • Stored: When historical data has been ingested, purpleair.get_historical_data serves from the database. Live current data is always fetched from the PurpleAir API.
ExamplesTools Reference