AQICN MCP Server

This is a Model Context Protocol (MCP) server that provides air quality data tools from the World Air Quality Index (AQICN) project. It allows LLMs to fetch real-time air quality data for cities and coordinates worldwide.

Installation

Installing via Smithery

To install AQICN MCP Server for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install @mattmarcin/aqicn-mcp --client claude

Installing via recommended uv (manual)

We recommend using uv to manage your Python environment:

# Install the package and dependencies uv pip install -e .

Related MCP server: Weather MCP Tool

Environment Setup

Create a .env file in the project root (you can copy from .env.example):

# .env AQICN_API_KEY=your_api_key_here

Alternatively, you can set the environment variable directly:

# Linux/macOS export AQICN_API_KEY=your_api_key_here # Windows set AQICN_API_KEY=your_api_key_here

Running the Server

Development Mode

The fastest way to test and debug your server is with the MCP Inspector:

mcp dev aqicn_server.py

Claude Desktop Integration

Once your server is ready, install it in Claude Desktop:

mcp install aqicn_server.py

Direct Execution

For testing or custom deployments:

python aqicn_server.py

Available Tools

1. city_aqi

Get air quality data for a specific city.

@mcp.tool() def city_aqi(city: str) -> AQIData: """Get air quality data for a specific city."""

Input:

city: Name of the city to get air quality data for

Output: AQIData with:

aqi: Air Quality Index value
station: Station name
dominant_pollutant: Main pollutant (if available)
time: Timestamp of the measurement
coordinates: Latitude and longitude of the station

2. geo_aqi

Get air quality data for a specific location using coordinates.

@mcp.tool() def geo_aqi(latitude: float, longitude: float) -> AQIData: """Get air quality data for a specific location using coordinates."""

Input:

latitude: Latitude of the location
longitude: Longitude of the location

Output: Same as city_aqi

3. search_station

Search for air quality monitoring stations by keyword.

@mcp.tool() def search_station(keyword: str) -> list[StationInfo]: """Search for air quality monitoring stations by keyword."""

Input:

keyword: Keyword to search for stations (city name, station name, etc.)

Output: List of StationInfo with:

name: Station name
station_id: Unique station identifier
coordinates: Latitude and longitude of the station

Example Usage

Using the MCP Python client:

from mcp import Client async with Client() as client: # Get air quality data for Beijing beijing_data = await client.city_aqi(city="beijing") print(f"Beijing AQI: {beijing_data.aqi}") # Get air quality data by coordinates (Tokyo) geo_data = await client.geo_aqi(latitude=35.6762, longitude=139.6503) print(f"Tokyo AQI: {geo_data.aqi}") # Search for stations stations = await client.search_station(keyword="london") for station in stations: print(f"Station: {station.name} ({station.coordinates})")