AQICN

Queries real-time AQI data from AQICN, returning full air quality details for Chinese cities via MCP.

python

0

GitHub Stars

python

Language

4 months ago

First Indexed

2 months ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "8xiang5hao-aqicn-mcp": {
      "command": "python",
      "args": [
        "/path/to/aqicn_mcp/src/aqicn_mcp/server.py"
      ],
      "env": {
        "AQICN_TOKEN": "your_token_here"
      }
    }
  }
}

You can query real-time air quality information for Chinese cities using this MCP server. It connects to AQICN’s data source and returns comprehensive air quality details, making it easy to build dashboards or alert systems around urban air conditions.

How to use

You interact with the AQICN MCP Server through your MCP client by calling the available city queries. Provide the city name in pinyin to obtain the current AQI value, pollutant details, health tips, and the overall air quality description for that location. Use natural language prompts to request the data you need, such as the current AQI for a city or the pollutant breakdown for a given day.

How to install

Prerequisites you need before installation: Python 3.8 or newer and Internet access to fetch dependencies.

cd /path/to/aqicn_mcp
pip install -e .

Configuration and usage notes

To run the MCP server, you must supply your API token from AQICN and point to the server script as shown in the configuration example.

{
  "mcpServers": {
    "aqicn": {
      "command": "python",
      "args": [
        "/path/to/aqicn_mcp/src/aqicn_mcp/server.py"
      ],
      "env": {
        "AQICN_TOKEN": "your_token_here"
      }
    }
  }
}

Troubleshooting

If you encounter issues starting the MCP server, verify Python path correctness, ensure dependencies are installed with pip install -e ., and confirm the AQICN_TOKEN is set correctly.

Project structure

The project layout includes the MCP server source, a test script, and configuration files. The main server script handles incoming MCP requests and fetches data from the AQICN API.

Notes on data and usage

Data returned includes the AQI index, air quality level, health recommendations, pollutant details (PM2.5, PM10, SO2, NO2, O3, CO, etc.), and the data update timestamp. The server sources data from AQICN and aligns with its terms of service.

Available tools

QueryAQI

Query live AQI for a city by its pinyin name and retrieve current AQI and health information.

PollutantDetails

Provide detailed pollutant measurements such as PM2.5, PM10, SO2, NO2, O3, CO, and other pollutants.

HealthGuidance

Return health recommendations based on the current air quality level.

CitySupport

Support queries for major Chinese cities and return structured air quality data.