Aqicn MCP

🚀 AQICN MCP Server

This is a Model Context Protocol (MCP) server that provides urban air quality management tools from the World Air Quality Index (AQICN) project. It allows Large Language Models (LLMs) to obtain real-time air quality data for global cities and coordinate locations.

🚀 Quick Start

✨ Features

• Provide urban air quality management tools from the AQICN project.
• Enable LLMs to access real - time air quality data for global cities and coordinate locations.

📦 Installation

Install via Smithery

To automatically install the AQICN MCP server for Claude Desktop, visit Smithery:

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

Manual Installation with uv (Recommended)

We recommend using uv to manage your Python environment:

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

Environment Configuration

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

# .env
AQICN_API_KEY=your_api_key_here

Or set the environment variables 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

Use the MCP checker for quick testing and debugging:

mcp dev aqicn_server.py

Integrate into Claude Desktop

When ready, install it to Claude Desktop:

mcp install aqicn_server.py

Direct Run

For testing or custom deployment:

python aqicn_server.py

💻 Usage Examples

Basic Usage

# Query the air quality of Beijing
result = city_aqi("Beijing")

# Query the air quality of a location based on coordinates
result = geo_aqi(39.9042, 116.5591)

# Search for all air quality monitoring stations
stations = search_station("Beijing")

Available Tools

1. city_aqi

Get the air quality data of a specific city.

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

Input:

• city: The name of the city to query.

Output: An AQIData object containing the following information:

• aqi: The Air Quality Index value.
• station: The name of the monitoring station.
• dominant_pollutant: The dominant pollutant (if any).
• time: The measurement timestamp.
• coordinates: The latitude and longitude of the monitoring station.

2. geo_aqi

Get the air quality data of a specific location based on coordinates.

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

Input:

• latitude: The latitude value.
• longitude: The longitude value.

Output: The 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: The search keyword (e.g., city name, station name).

Output: A list of StationInfo objects containing the following information:

• name: The name of the station.
• station_id: The unique station ID.
• coordinates: The latitude and longitude of the station.

Important Notes

⚠️ Important Note

Make sure you have obtained a valid API Key from the AQICN platform before installation.

💡 Usage Tip

If you have any questions, please visit GitHub to view the documentation or submit an issue.

Thanks for using the AQICN MCP Server!