seoul-timeavg-air-mcp

ソウル市の期間別時間平均大気環境情報を照会するMCP（Model Context Protocol）サーバです。 微細粉塵、超微細粉塵、オゾン、二酸化窒素、一酸化炭素、二酸化硫黄の時間平均データを 測定所／圏域単位で提供します。

データ出典

• 提供機関: ソウル特別市気候環境本部大気政策課

• プラットフォーム: ソウルオープンデータ広場 — サービス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ベースのレート制限 （1分あたり3回、1時間以内に429が5回以上で24時間ブロック、1日30回制限）が適用されています。

ライセンス

• コード: MIT License

• データ: 公共ヌリ1類型（出典表示、ソウル特別市）