What is Aqicn Mcp

aqicn-mcp is a Model Context Protocol (MCP) server that provides tools for accessing air quality data from the World Air Quality Index (AQICN) project. It enables users to retrieve real-time air quality information for various cities and geographical coordinates worldwide.

Use cases

Use cases for aqicn-mcp include obtaining air quality data for specific cities (e.g., Beijing), retrieving data based on geographical coordinates (e.g., Tokyo), and searching for air quality monitoring stations in a given area (e.g., London).

How to use

To use aqicn-mcp, you can install it via Smithery or manually using uv to manage your Python environment. After installation, set up your environment with an AQICN API key and run the server in development mode or directly execute it for testing.

Key features

Key features of aqicn-mcp include tools for retrieving air quality data by city name or geographical coordinates, searching for air quality monitoring stations, and providing detailed information such as AQI values, dominant pollutants, and measurement timestamps.

Where to use

aqicn-mcp can be used in various fields such as environmental monitoring, public health, urban planning, and research, where real-time air quality data is essential for decision-making and analysis.

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 .

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.