Airly MCP Server

An MCP server that integrates the Airly API, enabling natural language interaction with air quality data. Query real-time measurements, find nearby stations, and get air quality forecasts through any MCP-compatible client.

API Token

An Airly API token is required. Set it using the AIRLY_API_TOKEN environment variable.

Installing

npx (Node.js)

{
  "mcpServers": {
    "airly": {
      "command": "npx",
      "args": ["-y", "@jsynowiec/mcp-server-airly"],
      "env": {
        "AIRLY_API_TOKEN": "your-api-token"
      }
    }
  }
}

bunx (Bun)

{
  "mcpServers": {
    "airly": {
      "command": "bunx",
      "args": ["--bun", "@jsynowiec/mcp-server-airly"],
      "env": {
        "AIRLY_API_TOKEN": "your-api-token"
      }
    }
  }
}

Local development

Build the project first, then point your MCP client at the local build output:

{
  "mcpServers": {
    "airly": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server-airly/dist/index.js"],
      "env": {
        "AIRLY_API_TOKEN": "your-api-token"
      }
    }
  }
}

Configuration

Variable	Required	Default	Description
AIRLY_API_TOKEN	Yes		Airly API key
AIRLY_DEFAULT_LATITUDE	No		Default latitude (decimal degrees)
AIRLY_DEFAULT_LONGITUDE	No		Default longitude (decimal degrees)
AIRLY_LANGUAGE	No	en	Response language (en or pl)

Default coordinates must be set together. When configured, location-based tools use them as a fallback when the LLM doesn't provide coordinates.

Tools

get_measurement

Get interpolated air quality measurements for any location. Returns current pollutant concentrations, air quality index with health advice, and WHO standard compliance. Includes 24-hour history and forecast.

get_nearest_installation

Find the nearest air quality monitoring stations to a given location, sorted by proximity. Returns station metadata including address, coordinates, and sensor type.

get_installation_measurements

Get measurements from a specific station by its installation ID. Same response format as get_measurement.

get_installation

Get metadata for a specific monitoring station.

Resources

URI	Description
airly://meta/indexes	Air quality index types and level definitions
airly://meta/measurements	Measurement types with labels and units
airly://meta/standards	Air quality standards and pollutant limits

Resources are cached for the session lifetime.

Prompts

Prompt	Description
check_air_quality	Check current air quality at a location
air_quality_forecast	Get the 24-hour air quality forecast
find_nearest_station	Find nearby monitoring stations

Development

Prerequisites

• Bun >= 1.0 or Node.js >= 22
• An Airly API token

Setup

bun install
bun run build

Scripts

bun run build       # Compile TypeScript
bun run lint        # Run ESLint
bun run typecheck   # Type-check without emitting
bun run fmtcheck    # Check Prettier formatting
bun run format      # Apply Prettier formatting
bun run test        # Run tests
bun run dev:test    # Run tests in watch mode

Testing with MCP Inspector

AIRLY_API_TOKEN=your-token npx @modelcontextprotocol/inspector node dist/index.js

Release

The prepublishOnly script automatically runs build, lint, type-check, and tests before npm publish:

npm publish --access public

Disclaimer

This project is not affiliated with, endorsed by, or associated with Airly in any way. It is an independent, open-source integration built on the publicly available Airly API.

License

Released under the MIT License.