# AirVisual MCP

> AirVisual monitors global air quality and weather conditions instantly. It gives your agent real-time data on AQI, pollution levels, and meteorology for any location worldwide. You can check current readings for a specific city, find the nearest station using coordinates or IP address, or map out supported locations by country/state.

## Overview
- **Category:** iot-hardware
- **Price:** Free
- **Tags:** air-quality, aqi, pollution-tracking, environmental-monitoring, weather-data

## Description

Need to know what's really going on with the air? This MCP connects environmental monitoring data—AQI and weather—directly into your workflow. Instead of opening three different websites for pollution, climate forecasts, and local maps, you ask your agent once. It handles all that heavy lifting. You can drill down from a global overview to hyper-local readings from specific monitoring stations. The Vinkius catalog makes this connection simple; just subscribe and grant access. Your agent uses these tools to pull current AQI for major cities or pinpoint the exact environmental data nearest your IP address, letting you plan outdoor activities or run research without leaving your client app.

## Tools

### list_cities
Lists all supported cities within a specified state or region.

### get_city_data
Retrieves real-time AQI and weather data for a specific city you name.

### list_countries
Returns a list of every country the service monitors for air quality data.

### get_nearest_city_by_coords
Gets the air quality and weather metrics for the closest city using GPS coordinates.

### get_nearest_city_by_ip
Finds and retrieves data for the nearest monitored city based on your IP address.

### list_states
Provides a list of supported states within a specific country.

### get_station_data
Pulls granular environmental readings directly from a specific, named monitoring station.

## Prompt Examples

**Prompt:** 
```
What is the current air quality and weather in Tokyo, Japan?
```

**Response:** 
```
I've retrieved the data for Tokyo. The current AQI is 42 (Good), with the main pollutant being PM2.5. The weather is clear with a temperature of 18°C and 55% humidity.
```

**Prompt:** 
```
Check the air quality at the nearest city based on my IP.
```

**Response:** 
```
Based on your IP, the nearest city is San Francisco. The current AQI is 15 (Excellent). It's currently 14°C with moderate winds.
```

**Prompt:** 
```
List all supported states in Canada.
```

**Response:** 
```
I've found 13 supported states/provinces in Canada, including Ontario, British Columbia, Quebec, and Alberta. Which one would you like to explore for city data?
```

## Capabilities

### Get City Readings
Retrieve current air quality index and weather metrics for any specified city.

### Find Location by Coordinates
Pull data for the closest monitoring site using precise GPS latitude/longitude inputs.

### Find Location by IP Address
Determine and retrieve environmental metrics based on your current network IP address.

### Check Specific Stations
Access granular, detailed data from an individual monitoring station location.

### List Supported Locations
Browse the hierarchy to list all supported countries, states, or cities for future queries.

## Use Cases

### Planning a Field Site Inspection
An environmental consultant needs to assess air quality risk for an industrial park. The agent first uses `list_states` and `list_cities` to confirm the region, then uses `get_nearest_city_by_coords` with the site's GPS markers to generate a full pollution report.

### Emergency Response Team Dispatch
A dispatcher needs immediate local data. They simply ask 'What is the air quality here?' The agent uses `get_nearest_city_by_ip` and returns the current AQI, temperature, and wind speed instantly.

### Developing a Global Health Alert System
A developer needs to build alerts for multiple regions. They use `list_countries` to iterate through all available markets, then call `get_city_data` sequentially to check AQI in major urban centers.

### IoT Air Quality Triggering
A smart building manager wants the HVAC system to adjust when pollution hits a high mark. The agent monitors the specific station data using `get_station_data` and triggers the automation if AQI exceeds 100.

## Benefits

- You stop guessing about air quality. Instead of checking multiple websites, using `get_city_data` provides immediate, single-source metrics for any city.
- Need data right now? Use `get_nearest_city_by_ip`. You just need to ask your agent what's nearby, and it uses your IP address to pull the air quality report.
- Drill down past general readings. If you know a specific monitoring spot matters, use `get_station_data` for hyper-local insights.
- Building a script? First, run `list_countries`, then `list_states`, and finally `list_cities` to validate the full scope of supported locations before querying data.
- The system automatically handles location resolution. If you give it coordinates, use `get_nearest_city_by_coords` instead of trying to guess the city name.

## How It Works

The bottom line is that you just ask for the data; the system figures out where it needs to look.

1. Subscribe to this MCP and provide your AirVisual API key.
2. Your agent sends a request with specific location parameters (e.g., coordinates or city name).
3. The MCP executes the correct tool call, returning real-time AQI, weather, and pollution metrics directly to your client.

## Frequently Asked Questions

**How does get_nearest_city_by_ip work?**
It determines the nearest monitored city using your current IP address. It's fast, but remember this only gives a general area reading; for precision, use `get_nearest_city_by_coords`.

**Can I list all available locations with list_countries?**
Yes, running `list_countries` provides the full scope of nations supported. You can then follow up by using `list_states` to see the sub-regions within that country.

**Is get_city_data better than getting station data?**
It depends on your need. Use `get_city_data` for a quick, general read of an entire urban area. Use `get_station_data` when you need the exact metrics from one physical monitoring equipment.

**What if I don't know the state abbreviation?**
Run `list_countries` first to narrow down the nation, and then use `list_states`. This gives you a clear list of supported states for that country.

**What happens if I use an incorrect API key when calling get_city_data?**
The call fails with a 401 Unauthorized error. Always confirm your AirVisual API Key is active and properly entered into the Vinkius setup. You can verify credentials through the dedicated support portal.

**How frequently does get_station_data update its readings?**
The data freshness depends on the physical sensor at that station. While AirVisual provides real-time indexing, the actual reporting interval varies by location and pollutant type. Always check the reported timestamp for accuracy.

**If I use get_nearest_city_by_coords with coordinates outside a monitored area, what error do I receive?**
You will likely receive a 'No Data Available' or similar geographic boundary error. Make sure your GPS coordinates fall within the service coverage map provided by AirVisual to guarantee results.

**Are there rate limits when using list_cities repeatedly for many states?**
Yes, repeated bulk calls can trigger temporary rate limiting. Implement exponential backoff or use batch processing methods in your agent's code to avoid hitting API caps and ensure consistent performance.

**Can I get air quality data for my current location without entering coordinates?**
Yes! You can use the `get_nearest_city_by_ip` tool. The agent will use your requester IP address to find and return the AQI and weather data for the closest supported city automatically.

**How do I find out which cities are supported in a specific region?**
You can browse the hierarchy using `list_countries`, then `list_states` for a specific country, and finally `list_cities` for a specific state. This allows you to discover exactly which locations have active monitoring.

**Does this server provide data from specific monitoring stations?**
Yes, the `get_station_data` tool allows you to retrieve real-time data from a specific named monitoring station if you know its name and location details (city, state, country).