jma-typhoon-mcp

過去の台風がいつ、どこを通ったかを、気象庁の台風位置表とベストトラックで調べられます。年ごとの一覧と、台風ごとの時刻・位置・中心気圧・風速を取得できます。1951年以降を調べるには、ベストトラックを使います。

利用前に

uv と Git が必要です。Python 3.12以上に対応しています。APIキーの設定は不要です。

Related MCP server: roc-cwa-mcp

MCPクライアントに登録する

公開GitHubリポジトリから uvx で起動します。初回は依存関係の準備に時間がかかることがあります。

Codex

codex mcp add jma-typhoon-mcp -- uvx --python 3.12 --from git+https://github.com/koizumikento/jma-typhoon-mcp.git@main jma-typhoon-mcp
codex mcp list

codex mcp list で登録を確認し、Codexの新しいセッションで /mcp を開くと、接続状態を確認できます。Codexの公式設定ガイド

Codexのデスクトップアプリでは、設定の「MCP servers」でSTDIOサーバーを追加し、下のJSON例と同じコマンド・引数を指定する方法もあります。

Claude Desktop / Cursor

次のファイルに設定します。

• Claude Desktop（Windows） %APPDATA%/Claude/claude_desktop_config.json

• Claude Desktop（macOS） ~/Library/Application Support/Claude/claude_desktop_config.json

• Cursor .cursor/mcp.json（プロジェクト内）

既に mcpServers がある場合は、その中にサーバーの項目を追加してください。保存後にクライアントを再起動し、ツールが表示されるか確認します。設定ファイルの場所と接続手順

{
  "mcpServers": {
    "jma-typhoon-mcp": {
      "command": "uvx",
      "args": [
        "--python",
        "3.12",
        "--from",
        "git+https://github.com/koizumikento/jma-typhoon-mcp.git@main",
        "jma-typhoon-mcp"
      ]
    }
  }
}

uvx が見つからない場合は、設定のコマンドに実行ファイルの絶対パスを指定してください。

登録後は、チャットで次のように聞けます。

2025年の台風第1号の経路と、最も低かった中心気圧を教えて。

1951年の台風第1号がいつ、どこを通ったかをベストトラックで調べて。

MCPツール

結果の analysis は台風位置表で final、ベストトラックで best_track です。ベストトラックの revision_date は台風ごとのデータ改訂日です。

CLIで使う

結果は標準出力にUTF-8のJSONで返ります。

uvx --python 3.12 --from git+https://github.com/koizumikento/jma-typhoon-mcp.git@main jma-typhoon-mcp list-typhoons --year 2025
uvx --python 3.12 --from git+https://github.com/koizumikento/jma-typhoon-mcp.git@main jma-typhoon-mcp get-typhoon-track --year 2025 --number 1
uvx --python 3.12 --from git+https://github.com/koizumikento/jma-typhoon-mcp.git@main jma-typhoon-mcp list-best-track-typhoons --year 1951
uvx --python 3.12 --from git+https://github.com/koizumikento/jma-typhoon-mcp.git@main jma-typhoon-mcp get-best-track --year 1951 --number 1

Pythonから呼び出す

リポジトリをクローンし、依存関係を準備します。

git clone https://github.com/koizumikento/jma-typhoon-mcp.git
cd jma-typhoon-mcp
uv sync --locked

次の例を example.py に保存し、クローン先で uv run --locked python example.py を実行します。

import asyncio

from jma_typhoon_mcp import get_best_track, get_typhoon_track

print(asyncio.run(get_typhoon_track(year=2025, number=1)))
print(asyncio.run(get_best_track(year=1951, number=1)))

データの更新

MCP・CLI・Pythonは同じローカルキャッシュを使います。台風位置表は年別CSVを取得し、今年分は24時間、過去年は30日ごとに確認します。ベストトラックは全年分のZIPを取得し、24時間ごとに確認します。どちらも期限を過ぎた最初の照会時に更新を確認します。更新に失敗した場合は直前の正常な版を返し、cache.refresh_failed と cache.checked_at で失敗の有無と最後に確認できた日時を判別できます。初回取得に失敗した場合はエラーになります。

台風位置表の更新をすぐに確認するには、次を実行します。

uvx --python 3.12 --from git+https://github.com/koizumikento/jma-typhoon-mcp.git@main jma-typhoon-mcp refresh --year 2025

キャッシュはWindowsでは %LOCALAPPDATA%/jma-typhoon-mcp、その他では $XDG_CACHE_HOME/jma-typhoon-mcp または ~/.cache/jma-typhoon-mcp に保存されます。JMA_TYPHOON_CACHE_DIR で保存先を指定できます。

データの出典と利用条件

台風位置表には事後解析済みの確定値を使います。速報値は気象庁の年別ページにあるPDFで確認できます。ベストトラックはRSMC東京台風センターの公開アーカイブです。日時はUTC、風速はノットです。東経180度を超える値は西経の負値に変換します。風速や中心気圧が記録されていないときは null になります。利用する際は気象庁の出典を示し、加工した場合はその旨を明記してください。台風位置表・ベストトラックの配布ページ・気象庁ホームページ利用規約

MIT Licenseはこのリポジトリのコードに適用します。