Skip to main content
Glama
deenesjakoruzh
hlucent

airkorea-realtime-mcp

by hlucent
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

⚠️ 服务终止通知 本MCP服务器已于2026-08-23终止fly.io部署。 代码保留在仓库中供开发参考。

airkorea-realtime-mcp

这是一个MCP服务器，用于查询韩国环境公团AirKorea OpenAPI的实时大气污染信息·综合大气环境指数(CAI)·测量站信息。

提供的工具（5个）

工具

说明

get_station_realtime_air_quality

按测量站名称查询该测量站的实时大气污染测量信息(SO2/CO/O3/NO2/PM10/PM2.5，综合大气环境指数)

get_sido_realtime_air_quality

按市道名称查询该市道全部测量站的实时测量信息

get_station_cai

按测量站名称查询实时综合大气环境指数(CAI)

search_stations

按地址或测量站名称搜索测量站列表/坐标

get_nearby_stations

输入坐标查询周边测量站及距离

Related MCP server: seoul-air-quality-mcp

数据来源

  • 提供机构：韩国环境公团气候大气本部大气环境处大气政策支援部

  • 平台：公共数据门户 (data.go.kr)

  • 服务组：韩国环境公团_AirKorea_大气污染信息、韩国环境公团_AirKorea_测量站信息、 韩国环境公团_AirKorea_综合大气环境指数(CAI)查询服务（服务组代码 B552584）

  • 使用许可范围：署名-禁止修改（须遵守标注数据来源（环境部/韩国环境公团）的义务）

测量单位及等级标准

项目

SO2

CO

O3

NO2

PM10

PM2.5

单位

ppm

ppm

ppm

ppm

㎍/㎥

㎍/㎥

等级(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件）。

环境变量

变量名

说明

AIRKOREA_SERVICE_KEY

从公共数据门户获取的AirKorea服务密钥（Decoding密钥）

安装及运行（本地）

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体系不同）。

代码

含义

00

正常

03

No Data（无数据）

10

请求参数错误

11

缺少必需参数

20

服务访问被拒绝（未申请使用）

22

超过每日流量限制

30

未注册的服务密钥

31

服务密钥使用期限已过期

相关项目

AirKorea OpenAPI规模较大，将拆分为3个独立的MCP进行开发：

阶段

仓库

包含范围

1阶段（本项目）

airkorea-realtime-mcp

实时测量信息、CAI、测量站信息

2阶段

airkorea-forecast-alert-mcp

大气质量预报、细颗粒物警报、臭氧·黄沙注意报

3阶段

airkorea-statistics-mcp

市道·测量站统计（日/月平均）、CAI差以上测量站

许可证

MIT（代码）/ 遵循公共누리第1类型（署名）— 标注数据来源（环境部/韩国环境公团）

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivitySlowing
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • seoul-air-quality-mcp

    hlucent
    F
    license
    Not graded
    quality
    B
    maintenance
    MCP server for querying Seoul's official air quality data, including real-time and hourly measurements by district. Enables AI assistants to answer questions about fine dust and air pollution using public data from Seoul Open Data Plaza.
    -

  • airkorea-forecast-alert-mcp

    hlucent
    A
    license
    Not graded
    quality
    C
    maintenance
    Enables querying Korean air quality forecasts, weekly ultrafine dust forecasts, high-concentration PM2.5 forecasts, particulate matter alarm statuses, ozone advisories, and yellow dust advisories from the AirKorea OpenAPI.
    MIT