seoul-timeavg-air-mcp

这是一个MCP（模型上下文协议）服务器，用于查询首尔市按时间段划分的每小时平均大气环境信息。 提供可吸入颗粒物（PM10）、细颗粒物（PM2.5）、臭氧、二氧化氮、一氧化碳、二氧化硫的每小时平均数据， 可按测量站/区域单位查询。

数据来源

• 提供机构：首尔特别市气候环境本部大气政策科

• 平台：首尔开放数据广场 — 服务ID：OA-221， 服务名称：首尔市按时间段划分的每小时平均大气环境信息 (TimeAverageCityAir)

• 使用许可范围：公共누리 1类（注明出处，允许商业使用和修改）

提供的工具 (Tools)

get_time_average_air

查询指定测量日期时间（YYYYMMDDHHmm）的每小时平均大气环境信息。

• msrmt_dt（必填）：测量日期时间，YYYYMMDDHHmm 12位格式，且分钟（mm）必须为 00 （例如：202401011200）。实际测试发现，使用10位（YYYYMMDDHH）格式无法查询。

• start_index（可选，默认1）：查询起始位置

• end_index（可选，默认25）：查询结束位置（单次最多1000条）

• sarea_nm（可选）：区域名称（例如：市中心圈、西北圈）

• msrstn_nm（可选）：测量站名称（例如：钟路区、龙山区）

返回字段：测量日期时间、区域代码/名称、测量站代码/名称、可吸入颗粒物1小时（㎍/㎥）、可吸入颗粒物24小时（㎍/㎥）、 细颗粒物（㎍/㎥）、臭氧（ppm）、二氧化氮浓度（ppm）、一氧化碳浓度（ppm）、二氧化硫浓度（ppm）

search_stations

通过测量站名称或区域名称搜索特定时间点的大气环境数据。

• msrmt_dt（必填）

• sarea_nm（可选）

• msrstn_nm（可选）

安装与本地运行

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

环境变量

部署 (fly.io)

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

部署后Claude.ai连接器连接地址：

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

已知限制

• 认证密钥不是作为查询参数传递，而是作为URL路径段传递 (http://openAPI.seoul.go.kr:8088/{KEY}/{TYPE}/TimeAverageCityAir/...)。

• 单次可查询的最大条数为1000条（END_INDEX - START_INDEX ≤ 1000，超过时返回ERROR-336）。 使用示例密钥（sample）时，最多5条（ERROR-335）。

• MSRMT_DT仅12位（YYYYMMDDHHmm，分钟必须为00） 格式可正常查询。10位格式返回INFO-200（无数据）。

• 可选参数（区域名称/测量站名称）组合的实际测试结果：

  • 两者均省略：返回全部

  • 仅指定sarea_nm：按该区域正常过滤

  • 仅指定msrstn_nm（省略区域名称）：观察到API的异常行为，过滤器被忽略并返回全部数据。 本服务器检测到这种情况后，会按测量站名称对响应进行重新过滤后返回。

  • 两者均指定：正常过滤（交集）

• 不支持HTTPS（连接失败）。仅使用HTTP（端口8088）。

• 部分错误响应（例如：ERROR-335、ERROR-336）即使在TYPE=json请求下也会以XML格式返回。 本服务器优先尝试JSON解析，失败后回退到XML解析。

• 本服务器允许任何人无需API密钥即可作为连接器连接，因此应用了基于IP的速率限制 （每分钟3次，1小时内出现5次以上429错误则封禁24小时，每日限制30次）。

许可证

• 代码：MIT License

• 数据：公共누리 1类（注明出处，首尔特别市）