seoul-realtime-air-by-region-mcp

A MCP server that retrieves real-time air quality status by region (도심권/동북권/동남권/서북권/서남권) in Seoul.
Based on the RealtimeCityAir API from Seoul Open Data Plaza.

• Organization/Department: Seoul Metropolitan Government Climate and Environment Headquarters Air Quality Policy Division

• Source Data: Seoul Open Data Plaza — Seoul Real-time Air Quality by Region

• License (Data): Public Open Type 1 (Attribution, commercial use and modification allowed)

• License (Code): MIT

Provided Tools

get_realtime_air_by_region

Retrieves real-time air quality status by region (or specific region/station).

Return fields: measurement datetime (MSRMT_DT), region (SAREA_NM), station (MSRSTN_NM), PM10 (PM, ㎍/㎥), PM2.5 (FPM, ㎍/㎥), ozone (OZON, ppm), nitrogen dioxide (NTDX, ppm), carbon monoxide (CBMX, ppm), sulfur dioxide (SPDX, ppm), integrated air quality grade (CAI_GRD), integrated air quality index (CAI_IDX), index determining substance (CRST_SBSTN).

list_available_regions

Returns a fixed list of 5 available region names (도심권/동북권/동남권/서북권/서남권). No API call.

Related MCP server: mcp-waqi

Constraints Verified Through Actual Measurements

• The API key is passed as a URL path segment (/{KEY}/json/RealtimeCityAir/...), not as a query parameter.

• msrstn_nm cannot be used alone without sarea_nm. Due to the API path structure, optional parameters are fixed in order: SAREA_NM position → MSRSTN_NM position. If you omit sarea_nm and pass only msrstn_nm, the value is interpreted as the SAREA_NM position, resulting in INFO-200 (no data). This server filters requests with only msrstn_nm before calling the API and returns a clear error.

• Expanding the start_index/end_index range returns multiple items normally (25 items confirmed for full query).

• Normal responses are JSON, but some error responses (e.g., invalid key INFO-100) return XML even when TYPE=json is requested. This server uses a fallback parser that extracts XML <CODE>/<MESSAGE> when JSON parsing fails.

• CAI_GRD (integrated air quality grade) values observed as "좋음" (good) and "보통" (moderate) at the time of measurement ("나쁨" and "매우나쁨" were not observed, but they may exist according to the specification).

Installation and Execution (Local)

git clone https://github.com/hlucent/seoul-realtime-air-by-region-mcp.git
cd seoul-realtime-air-by-region-mcp
pip install -r requirements.txt
cp .env.example .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, when connecting to the Claude.ai connector, register it by appending the /mcp path as below:

https://<앱이름>.fly.dev/mcp

Security

This server is exposed without an API key, and an IP-based 3-tier rate limit is applied
(3 times per minute — can be effectively relaxed in multi-machine deployments proportionally to the number of machines; 5 violations per hour results in a 24-hour block; daily total limit of 30).

IP is determined primarily from the Fly-Client-IP header (set by fly.io edge, cannot be forged by clients).
The rate limit counter is kept in memory (dict) per process and not shared between machines, so if fly.io distributes requests across multiple machines, the effective limit for the same IP can be relaxed to "3 per minute × number of running machines". This is a design trade-off for implementing in-memory without external storage.

License

MIT License. The original data follows Public Open Type 1.