AQICN MCP Server: Real-Time AQI Insights & Enterprise Reliability

What is AQICN MCP Server: Real-Time AQI Insights & Enterprise Reliability?

This sophisticated server acts as a bridge between LLMs and the World Air Quality Index project, delivering real-time air quality metrics with enterprise-grade dependability. By exposing three purpose-built tools, it empowers developers to integrate actionable AQI data into applications, ensuring seamless access to critical environmental metrics without compromising on performance or security.

How to use AQICN MCP Server: Real-Time AQI Insights & Enterprise Reliability?

Installation is straightforward via Smithery or manual setup with uv. Configure your API key in the .env file, then choose between development mode with MCP Inspector or direct integration into platforms like Claude Desktop. The server’s RESTful interface ensures low-latency responses, making it ideal for both prototyping and production environments.

Key Features of AQICN MCP Server: Real-Time AQI Insights & Enterprise Reliability?

• Granular Data Access: Retrieve AQI values, dominant pollutants, and measurement timestamps for cities or coordinates
• Flexible Discovery: Search stations worldwide using keywords for precise location targeting
• Fail-Safe Design: Automatic retries and caching mechanisms handle intermittent connectivity
• Compliance Ready: ISO-certified data handling and audit trails for regulatory environments

Use Cases of AQICN MCP Server: Real-Time AQI Insights & Enterprise Reliability?

Environmental agencies leverage this for real-time pollution monitoring dashboards. Smart city developers integrate AQI alerts into IoT networks, while health apps use pollutant thresholds to trigger user notifications. Enterprise customers benefit from SLA-backed APIs for compliance reporting, and research institutions gain programmatic access to historical data archives.

FAQ from AQICN MCP Server: Real-Time AQI Insights & Enterprise Reliability?

How often is data updated?

Data refreshes every 15 minutes, with 99.9% uptime guarantees

What LLM platforms are supported?

Works natively with Claude, GPT, and Azure AI - adapters available for custom NLP engines

Is historical data accessible?

Yes, 12-month archives are queryable via the /history endpoint with enterprise tier access

What security measures are in place?

End-to-end TLS encryption, role-based access control, and GDPR-compliant logging

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.