# jma-typhoon-mcp

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

## 利用前に

[uv](https://docs.astral.sh/uv/) と Git が必要です。Python 3.12以上に対応しています。APIキーの設定は不要です。

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

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

### Codex

```sh
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の公式設定ガイド](https://learn.chatgpt.com/docs/extend/mcp?surface=cli)

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` がある場合は、その中にサーバーの項目を追加してください。保存後にクライアントを再起動し、ツールが表示されるか確認します。[設定ファイルの場所と接続手順](https://py.sdk.modelcontextprotocol.io/get-started/real-host/)

```json
{
  "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ツール

| ツール | 用途 |
| --- | --- |
| `list_typhoons` | 台風位置表にある確定済みの台風を年ごとに一覧（2001年以降） |
| `get_typhoon_track` | 台風位置表の経路を年と台風番号で取得（2001年以降） |
| `list_best_track_typhoons` | RSMC東京台風センターのベストトラックにある台風を年ごとに一覧（1951年以降） |
| `get_best_track` | ベストトラックの経路を年と台風番号で取得（1951年以降） |

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

## CLIで使う

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

```sh
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から呼び出す

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

```sh
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` を実行します。

```python
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` で失敗の有無と最後に確認できた日時を判別できます。初回取得に失敗した場合はエラーになります。

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

```sh
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` になります。利用する際は気象庁の出典を示し、加工した場合はその旨を明記してください。[台風位置表](https://www.data.jma.go.jp/typhoon/position_table/index.html)・[ベストトラックの配布ページ](https://www.jma.go.jp/jma/jma-eng/jma-center/rsmc-hp-pub-eg/besttrack.html)・[気象庁ホームページ利用規約](https://www.jma.go.jp/jma/kishou/info/coment.html)

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