AQICN MCP Server

View original on GitHub

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 .

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})")

Contributing

Feel free to open issues and pull requests. Please ensure your changes include appropriate tests and documentation.

License

This project is licensed under the MIT License.