airkorea-realtime-mcp

这是 한국환경공단 에어코리아 OpenAPI 的 实时大气污染信息 · 综合大气环境指数(CAI) · 测量站信息 查询 MCP 服务器。

提供的工具（5个）

Related MCP server: mcp-waqi

数据来源

• 提供机构：한국환경공단 기후대기본부 대기환경처 대기정책지원부

• 平台：공공데이터포털 (data.go.kr)

• 服务组：한국환경공단_에어코리아_대기오염정보、한국환경공단_에어코리아_측정소정보、 한국환경공단_에어코리아_통합대기환경지수(CAI) 조회 서비스（服务组代码 B552584）

• 使用许可范围：署名-禁止修改（必须标注资料来源（환경부/한국환경공단））

测量单位及等级标准

等级（Grade）值：1=好，2=普通，3=差，4=非常差

已知限制（实测确认的事项）

• 测量站列表（search_stations）坐标轴：固定调用 ver=1.1 时，确认 dmX=经度，dmY=纬度（已用5个不同测量站交叉验证）。基于WGS84。

• 邻近测量站查询（get_nearby_stations）坐标系：实测确认，直接输入WGS84经纬度会得到完全错误的结果（例如输入首尔江南区坐标时返回济州岛测量站）。必须进行TM中央原点（EPSG:5181）坐标转换，本服务器使用pyproj自动将WGS84→EPSG:5181转换后调用API（用户只需输入经纬度）。输入江南区厅坐标（37.515336, 127.049357）时，江南区测量站以距离0.4km返回为最优先，验证了转换精度。

• CAI查询（get_station_cai）响应字段：与规范表（khaiValue/khaiGrade/khaiItem）不同，实际字段名为caiValue/caiGrade/caiItem。全部字段为stationCode、stationName、mangName、dataTime、caiValue、caiGrade、caiItem（个别污染物字段如so2Value等不包含在此操作的响应中）。

• CAI查询的正常resultCode：其他4个操作正常时返回resultCode="00"，但只有getMsrstnKhaiRltmDnsty（CAI）正常时返回resultCode="200"、resultMsg="NORMAL_CODE"。服务器代码将resultMsg为"NORMAL_CODE"/"NORMAL SERVICE"的情况也视为正常。

• items响应结构差异：ArpltnInforInqireSvc/MsrstnInfoInqireSvc的items是数组，而RltmKhaiInfoSvc（CAI）的items.item多了一层包装。服务器吸收此差异，始终返回数组。

• 缺失值表示：本次实测范围（正常大气质量数据）中未出现"-"缺失情况，但根据规范示例，_safe_numeric已实现将"-"/None/空字符串/浮点数（float）均安全转换为None（不随意替换为0）。

• API服务器稳定性：实测中确认SERVICETIMEOUT_ERROR（错误代码05，HTTP 504）频繁发生。服务器仅对代码05自动重试最多3次。

• sidoName "전남광주"：正常查询（反映2026年전남광주특별시成立，确认totalCount 64件）。

环境变量

安装及运行（本地）

pip install -r requirements.txt --break-system-packages
cp .env.example .env   # AIRKOREA_SERVICE_KEY 값 입력
python server.py

部署（fly.io）

fly launch --no-deploy
# fly.toml이 [http_service] 방식인지 확인 후
fly secrets set AIRKOREA_SERVICE_KEY=발급받은키
flyctl deploy

Claude.ai 连接器连接

部署完成后，在地址后添加/mcp进行连接。

https://airkorea-realtime-mcp.fly.dev/mcp

Rate Limit 策略

由于是无需API密钥仅凭URL即可连接的公开服务器，因此基于IP应用3级rate limit。

• 每分钟超过3次返回429（多机部署时可根据机器数量成比例实际缓解）

• 1小时内收到5次以上429则封禁24小时

• 每日（滚动24小时）总计超过30次返回429

错误代码

此API使用공공데이터포털标准错误代码体系（与首尔市开放数据广场的INFO-000/ERROR-3xx体系不同）。

相关项目

에어코리아 OpenAPI规模较大，将分为3个独立MCP开发：

许可证

MIT（代码）/ 遵循공공누리第1类（署名）— 标注数据来源（환경부/한국환경공단）