AQICN

Provides real-time AQI data for Chinese cities via MCP, including pollutants and health guidance.

python

0

GitHub Stars

python

Language

6 months ago

First Indexed

3 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": {
    "tinofish-aqicn-mcp": {
      "command": "python",
      "args": [
        "/path/to/aqicn_mcp/src/aqicn_mcp/server.py"
      ],
      "env": {
        "AQICN_TOKEN": "your_token_here"
      }
    }
  }
}

This MCP server lets you look up real-time air quality information for Chinese cities by city name in pinyin. It returns comprehensive data such as AQI, pollutant details, health guidance, and a city-specific air quality description, all accessible through your MCP client.

How to use

You interact with this MCP server by running it locally and then querying it from your MCP client using the city name in pinyin. You can ask for the current air quality of a city and receive the full data set, including AQI, pollutant concentrations, and health recommendations. Use natural language prompts like those shown in examples to trigger the data retrieval.

How to install

Prerequisites: Python 3.8+ and a working Python environment.

Install the MCP server package in editable mode.

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

Obtain your API token from AQICN by registering for an API key.
Test the API connection using the provided test script.

python test_aqicn.py

Configuration and usage tips

Configure the MCP server by adding the following to your MCP configuration under mcpServers. This sets up a local stdio MCP server using Python to run the server script and passes your AQICN API token.

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

Notes and security

Replace "/path/to/aqicn_mcp" with the actual absolute path to your project.
Replace your_token_here with the actual AQICN API token you obtained.

Troubleshooting

If the MCP server cannot start, verify your Python path, ensure all dependencies are installed with pip install -e ., and confirm the AQICN_TOKEN environment variable is set correctly.

If a query fails, check that the API token is valid, ensure network connectivity, verify city pinyin spelling, and confirm the AQICN service is reachable.

Project structure and tech stack

Project structure includes the server script, a test script, and configuration files. It is built with Python 3.8+ and uses the MCP SDK and asynchronous HTTP client libraries to fetch data from AQICN.