AQICN

You can run an MCP server that fetches real-time air quality data from AQICN and expose simple tools for city-based, location-based, and station-based queries. This server is useful when you want reliable, programmatic access to air quality metrics for integration with LLM workflows or other automation.

How to use

You interact with the AQICN MCP Server through an MCP client. The server exposes tools you can call directly from your client code to retrieve real-time air quality information.

Available tools you can use in your client include getting air quality data for a specific city, retrieving data by geographic coordinates, and searching for monitoring stations by a keyword. Use them to build flows like: determine the air quality for a given city, check a location’s current AQI, or discover nearby stations for on-site measurements.

Key tools you will call are:

• city_aqi(city: str) -> AQIData: fetches air quality data for a named city.

• geo_aqi(latitude: float, longitude: float) -> AQIData: fetches air quality data for a location using coordinates.

• search_station(keyword: str) -> list[StationInfo]: searches for air quality monitoring stations by a keyword.

How to install

Prerequisites you need before installation:

• Python 3.x installed on your system

• uvx (for managing Python environments) or an alternative Python environment manager

• Node.js and npm for optional client tooling or integration helpers

• Access to an AQICN API key to query data

Follow these steps to install the server locally in a straightforward flow.

# Step 1: Install the MCP server package (manual install path) 
uv pip install -e .

# Step 2: Create the environment file and set your API key
# in the project root
# .env
AQICN_API_KEY=your_api_key_here

# Step 3: Run the server in development mode to test locally
mcp dev aqicn_server.py

# Step 4: Run the server directly (for testing or custom deployment)
python aqicn_server.py

# Optional: install for Claude Desktop integration if you use that client
npx -y @smithery/cli install @mattmarcin/aqicn-mcp --client claude

Additional notes and configuration

Environment configuration is required to access AQICN data. Create a .env file at the project root or set the environment variable AQICN_API_KEY with your API key. This key authenticates your requests to AQICN.

Two practical ways to run the server are described here. Use the development command to quickly test and debug, or run the Python script directly for a production-like startup.

# Development mode (with MCP Inspector for quick testing)
mcp dev aqicn_server.py

# Direct execution (production-friendly start)
python aqicn_server.py

Available tools

city_aqi

Fetches air quality data for a specific city and returns an AQIData structure with aqi, station, dominant_pollutant, time, and coordinates.

geo_aqi

Fetches air quality data for a location defined by latitude and longitude and returns the same AQIData structure as city_aqi.

search_station

Searches for air quality monitoring stations by a keyword and returns a list of StationInfo with name, station_id, and coordinates.