weather-forecast-mcp

气象厅短期预报查询服务（VilageFcstInfoService_2.0）作为 MCP（Model Context Protocol）服务器提供。可通过区域名或格点坐标（nx, ny）查询超短时实况、超短期预报、短期预报、预报版本4种操作。

Dataset Registry

本 MCP 仅由单一 API（4种操作）组成，没有任何额外的数据集集成。

提供工具

安装及部署

pip install -r requirements.txt
cp .env.example .env  # WEATHER_FORECAST_SERVICE_KEY 값 입력
python server.py

fly.io 部署：

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

环境变量

区域指定方式

输入 area_name（例如：“서울 중구”、“종로구 청운효자동”）或 nx/ny 格点坐标之一。 使用 area_name 时，会从内置的格点映射表（3,838个行政区域）中按 3级（읍면동）→ 2级（시군구）→ 1级（시도）的顺序自动匹配。

Rate Limit

由于是公开服务器特性，适用以下三级限制：

• 每分钟超过 3 次 → 429

• 1小时内违反 5 次 → 24小时封禁

• 每日超过 30 次 → 429

在 fly.io 多机（2台）环境中，rate limit 计数器可能按机器彼此独立，这一点作为已知的权衡予以接受（以可用性优先）。

实测确认事项

• get_vilage_fcst 的 numOfRows 默认设置为 1000（实测确认示例响应 totalCount 742~944 条，若默认值 10 则会被截断）

• dataType=JSON 的错误响应实际以 JSON 格式返回（实测错误的 nx/ny 请求时也能正常收到 resultCode: "10" 的 JSON）。此外，为以防万一也实现了 XML <resultCode>/<resultMsg> 正则表达式回退

• 对 get_vilage_fcst 指定无效的 base_time（例如：凌晨3点）时，会返回 resultCode: "03"（NO_DATA）错误（是显式错误，而非空响应）

• 实测确认了短期预报 +4天以后（延长期间）PCP/SNO/WSD 会以定性信息代码（1=少/2=一般/3=多）返回。当 fcstDate 相对 baseDate 达到 +4天及以上时，服务器应用该代码表，并在响应中标示 is_extended_period: true

• get_fcst_version 以与 base_time 相同的 YYYYMMDDHHmm 格式传入 basedatetime，确认可正常工作（以 ftype=SHRT 为准）

许可证

MIT

参考

• 原始 API 规格：气象厅《短预报查询服务（2.0）Open API 活用指南》

• 格点-经纬度映射表：气象厅提供的 Excel 资料（2026年7月为准，3,838个行政区域）

• 仅提供韩国（南韩）地区（北韩及海外不提供）