seoul-timeavg-air-mcp

This is an MCP (Model Context Protocol) server that queries time-average air environment information for Seoul by period. It provides hourly average data for particulate matter (PM10), fine particulate matter (PM2.5), ozone, nitrogen dioxide, carbon monoxide, and sulfur dioxide, by measuring station/zone.

Data Source

• Provider: Seoul Metropolitan Government Climate and Environment Headquarters, Air Quality Policy Division

• Platform: Seoul Open Data Plaza — Service ID: OA-221, Service Name: TimeAverageCityAir

• License: Public Nuri Type 1 (Attribution required, commercial use and modification allowed)

Provided Tools

get_time_average_air

Retrieves time-average air environment information for a specified measurement date/time (YYYYMMDDHHmm).

• msrmt_dt (required): Measurement date/time, YYYYMMDDHHmm 12-digit format, with minutes (mm) always 00 (e.g., 202401011200). Not queried with 10-digit actual measurement results (YYYYMMDDHH).

• start_index (optional, default 1): Start position for query

• end_index (optional, default 25): End position for query (up to 1000 records at a time)

• sarea_nm (optional): Zone name (e.g., Downtown Zone, Northwest Zone)

• msrstn_nm (optional): Station name (e.g., Jongno-gu, Yongsan-gu)

Return fields: Measurement date/time, zone code/name, station code/name, PM10 1-hour (㎍/㎥), PM10 24-hour (㎍/㎥), PM2.5 (㎍/㎥), ozone (ppm), nitrogen dioxide (ppm), carbon monoxide (ppm), sulfur dioxide (ppm)

search_stations

Searches for air environment data at a specific time by station name or zone name.

• msrmt_dt (required)

• sarea_nm (optional)

• msrstn_nm (optional)

Installation and Local Execution

git clone https://github.com/hlucent/seoul-timeavg-air-mcp.git
cd seoul-timeavg-air-mcp
pip install -r requirements.txt
cp .env.example .env
# .env에 SEOUL_API_KEY=발급받은키 입력
python server.py

Environment Variables

Deployment (fly.io)

fly launch --no-deploy
fly secrets set SEOUL_API_KEY=발급받은키
flyctl deploy

After deployment, the connector connection address for Claude.ai:

https://seoul-timeavg-air-mcp.fly.dev/mcp

Known Limitations

• The authentication key is passed as a URL path segment, not as a query parameter (http://openAPI.seoul.go.kr:8088/{KEY}/{TYPE}/TimeAverageCityAir/...).

• The maximum number of records retrievable at once is 1000 (END_INDEX - START_INDEX ≤ 1000, exceeding this returns ERROR-336). When using the sample key (sample), the maximum is 5 records (ERROR-335).

• MSRMT_DT is only correctly queried in 12-digit format (YYYYMMDDHHmm, minutes always 00). Using 10 digits returns INFO-200 (no data).

• Actual test results for optional parameter (zone name/station name) combinations:

  • Both omitted: Returns all records

  • Only sarea_nm specified: Filters correctly by the zone

  • Only msrstn_nm specified (zone name omitted): Confirmed API-specific behavior where the filter is ignored and all records are returned. This server detects this case and re-filters the response by station name.

  • Both specified: Correct filtering (intersection)

• HTTPS is not supported (connection fails). Only HTTP (port 8088) is used.

• Some error responses (e.g., ERROR-335, ERROR-336) are returned as XML even for TYPE=json requests. This server prioritizes JSON parsing and falls back to XML on failure.

• Since this server can be connected by anyone without an API key, IP-based rate limiting applies (3 requests per minute, 24-hour block if 5 or more 429 responses occur within 1 hour, daily limit of 30 requests).

License

• Code: MIT License

• Data: Public Nuri Type 1 (Attribution, Seoul Metropolitan Government)