japan-climate-stats-mcp
README.md
# japan-climate-stats-mcp
**Sub-100ms Japanese 47 Prefectures & Municipal Climate / Environment Statistics MCP Server powered by Open-Meteo API**
**APIキー不要の `Open-Meteo API` ＆ ローカル高速キャッシュを活用し、日本の全47都道府県・主要都市（JIS都道府県・市区町村コード・緯度経度対応）の「年間日照時間・平均気温・冬場の寒暖差・降水量・猛暑日数」を0.1秒未満で算出し、あらゆる地域統計データとクロス分析できる 1ツール特化型 MCP サーバー**
[](LICENSE)
[](https://modelcontextprotocol.io)
[](https://www.python.org/)
[](https://open-meteo.com/)
[English](#english-documentation) | [日本語ドキュメント](#japanese-documentation)
---
<a name="english-documentation"></a>
## 🌍 English Documentation
### Why `japan-climate-stats-mcp`?
When analyzing regional socioeconomic trends—such as solar/renewable energy adoption, vacant house ratios, mortality/healthcare demand, agricultural output, or real estate prices—**climate and natural environment factors (sunshine duration, winter coldness/diurnal temperature swings, extreme heat days, and annual precipitation)** are critical physical drivers.
However, feeding raw meteorological data into local LLMs (**Qwen3-8B**, **Llama-3**, **Mistral** via LM Studio / Ollama) or cloud AI agents (**Claude Desktop**, **Cursor**, **Cline**) typically requires complex geocoding, daily weather aggregation, and JIS administrative code alignment.
**`japan-climate-stats-mcp`** solves this in a single, zero-API-key MCP tool (`get_climate_environment_stats`):
- **Instant JIS Code & Coordinate Normalization**: Accepts `"all_prefectures"` (all 47 prefectures at once), Japanese/English prefecture or city names (`"東京都"`, `"Sapporo"`, `"軽井沢町"`), 2-digit JIS prefecture codes (`"01"`–`"47"`), 5-digit JIS municipality codes (`"01100"`, `"13101"`), or arbitrary `lat`/`lon` coordinates.
- **Ready-to-Join Output Schema**: Every record attaches `prefecture_code`, `prefecture_ja`, `prefecture_en`, `prefecture`, `municipality_code`, `lat`, `lon`, and `year`—joining directly with [`japan-data-mcp`](https://github.com/japan-opendata-lab/japan-data-mcp) and [`correlation-discovery-mcp`](https://github.com/japan-opendata-lab/correlation-discovery-mcp) with zero schema conversion.
- **Sub-100ms Response & Offline Resilience**: Combines live Open-Meteo Archive / Forecast HTTPS API aggregation with a local JSON cache and verified 47-prefecture climate baseline statistics for **<0.01s (<10ms)** response times and 100% offline reliability.
- **One-Click Parquet Export (`export_parquet=True`)**: Exports a standardized `.parquet` file into your shared data directory so `correlation-discovery-mcp` automatically includes climate indicators in cross-dataset correlation and driver scans.
- **Enterprise-Grade Security & Sandboxing**:
- **SSRF Protection**: Outbound HTTP requests are strictly restricted to HTTPS endpoints on `api.open-meteo.com` and `archive-api.open-meteo.com`.
- **Path Traversal Guard**: File writes (JSON cache & Parquet export) are strictly confined to the sandboxed directory via `Path.resolve()` and `relative_to()` (`../` rejected) with zero file-deletion capabilities.
- **Prompt Injection Defense**: External/untrusted text inputs are sanitized and wrapped in `<untrusted_data>...</untrusted_data>` boundary tags.
---
### 📊 Climate & Environment Indicators Returned (`get_climate_environment_stats`)
| Column Name | Type | Unit | Description |
| :--- | :--- | :--- | :--- |
| `prefecture_code` | `string` | JIS 2-digit | Standardized JIS prefecture code (`"01"` to `"47"`) |
| `prefecture_ja` / `prefecture` | `string` | — | Japanese prefecture name (`"北海道"`, `"東京都"`, ..., `"沖縄県"`) |
| `prefecture_en` | `string` | — | English prefecture name (`"Hokkaido"`, `"Tokyo"`, ..., `"Okinawa"`) |
| `municipality_code` | `string` | JIS 5-digit | Standardized 5-digit JIS municipality code (`"01100"`, `"13101"`, etc.) |
| `lat` / `lon` | `float` | degrees | Latitude & Longitude (WGS84) |
| `annual_sunshine_hours` | `float` | hours | Annual cumulative sunshine duration |
| `mean_temp_c` | `float` | °C | Annual mean air temperature (2m) |
| `max_temp_c` / `min_temp_c` | `float` | °C | Annual extreme maximum & minimum temperature |
| `winter_temp_mean_c` | `float` | °C | Winter (Dec–Feb) mean air temperature |
| `winter_temp_range_c` | `float` | °C | Winter diurnal temperature swing / thermal stress index |
| `annual_temp_range_c` | `float` | °C | Annual temperature range (`max_temp_c - min_temp_c`) |
| `annual_precipitation_mm` | `float` | mm | Annual total precipitation |
| `extreme_hot_days` | `int` | days/year | Number of extreme hot days ($\text{daily max} \ge 35.0^\circ\text{C}$, *Moshobi*) |
| `hot_summer_days` | `int` | days/year | Number of hot summer days ($\text{daily max} \ge 30.0^\circ\text{C}$, *Manatsubi*) |
| `frost_winter_days` | `int` | days/year | Number of frost/winter days ($\text{daily min} < 0.0^\circ\text{C}$, *Fuyubi*) |
| `ice_days` | `int` | days/year | Number of ice/true-winter days ($\text{daily max} < 0.0^\circ\text{C}$, *Mafuyubi*) |
| `heavy_rain_days` | `int` | days/year | Number of heavy rain days ($\text{daily precipitation} \ge 50.0\text{mm}$) |
---
### 🚀 Quick Start
#### 1. Installation
```bash
git clone https://github.com/japan-opendata-lab/japan-climate-stats-mcp.git
cd japan-climate-stats-mcp
pip install -e ".[dev]"
pytest -v
```
#### 2. Configure in LM Studio (`~/.lmstudio/mcp.json`) or Claude Desktop / Cursor
```json
{
"mcpServers": {
"japan-climate-stats-mcp": {
"command": "python",
"args": [
"-X",
"utf8",
"./oss_mcp/japan-climate-stats-mcp/server.py"
],
"env": {
"PYTHONIOENCODING": "utf-8",
"CLIMATE_CACHE_DIR": "./oss_mcp/japan-climate-stats-mcp/.cache",
"CLIMATE_EXPORT_DIR": "./oss_mcp/japan-climate-stats-mcp/.cache"
}
}
}
}
```
---
### 🔗 Cross-Analysis Examples with `correlation-discovery-mcp` & `japan-data-mcp`
By setting `export_parquet=True` in `get_climate_environment_stats` and adding the export folder to `DATA_SOURCE_DIR` of [`correlation-discovery-mcp`](https://github.com/japan-opendata-lab/correlation-discovery-mcp), your local LLM or AI agent can immediately cross-scan climate statistics against 162+ official Japanese socioeconomic datasets from [`japan-data-mcp`](https://github.com/japan-opendata-lab/japan-data-mcp):
1. **Sunshine Hours vs. Solar Renewable Energy Adoption**:
- Call `get_climate_environment_stats(location="all_prefectures", export_parquet=True)` to generate `japan_climate_environment_stats.parquet` (top sunshine prefectures: Yamanashi `2,225.8h`, Kochi `2,168.4h`, Miyazaki `2,154.2h`, Shizuoka `2,145.0h`, Gunma `2,132.5h`).
- Call `discover_correlations(mode="pair", table_x="japan_climate_environment_stats", column_x="annual_sunshine_hours", table_y="renewable_energy", join_key="prefecture")` to quantify how physical solar irradiation drives regional FIT/FIP solar capacity and identify policy-driven outlier prefectures.
2. **Winter Coldness & Diurnal Range vs. Vacant Houses & Demographics**:
- Cross-reference `frost_winter_days` and `winter_temp_range_c` against `vacant_houses` and `demographics` via `municipality_code` or `prefecture` to analyze depopulation and housing abandonment in heavy-snow / cold-winter regions vs. inland basins.
3. **Extreme Heat Days vs. Emergency Medical & Hospital Infrastructure**:
- Cross-reference `extreme_hot_days` ($\ge 35^\circ\text{C}$) with `medical` (hospital bed capacity & emergency clinics from `japan-data-mcp`) to evaluate heatstroke vulnerability across aging municipalities.
---
<a name="japanese-documentation"></a>
## 🇯🇵 日本語ドキュメント
### なぜ `japan-climate-stats-mcp` が必要なのか？
太陽光発電（再エネ）の導入ポテンシャル、空き家率や人口流出、冬季の医療・介護需要、農業生産高、観光・不動産価格などの地域データを分析する際、**「年間日照時間」「平均・最高・最低気温」「冬場の寒暖差（日較差・冬季冷え込み）」「年間降水量」「猛暑日数・冬日数」**といった気象・自然環境データは極めて重要な説明変数（交絡因子・物理的ドライバー）になります。
**`japan-climate-stats-mcp`** は、APIキー不要の `Open-Meteo API` とローカル高速キャッシュを組み合わせ、単一の統合ツール `get_climate_environment_stats` で以下を実現するオープンソース MCP サーバーです。
### 4大特徴
1. **1ツール統合 ＆ JIS都道府県・市区町村コード・任意座標の完全正規化**
- `location="all_prefectures"` で**全47都道府県を一括取得**できるほか、都道府県名（`"北海道"`, `"東京都"`, `"Tokyo"` 等）、主要市区町村名（`"札幌市"`, `"横浜市"`, `"軽井沢町"`, `"石垣市"` 等）、2桁JIS都道府県コード（`"01"`〜`"47"`）、5桁JIS市区町村コード（`"01100"`, `"13101"` 等）、および任意の `lat` / `lon` 緯度経度指定に対応。
- すべての返却レコードに標準化された `prefecture_code`, `prefecture_ja`, `prefecture_en`, `prefecture`, `municipality_code`, `lat`, `lon`, `year` を自動付与します。
2. **0.1秒未満（<10ms）の超高速応答 ＆ 完全オフライン耐性**
- ローカル JSON キャッシュ機構と、気象庁平年値・Open-Meteo実測値に準拠した「全47都道府県・主要都市の基準気候ベースライン統計」を内蔵。
- キャッシュヒット時やベースライン参照時は **0.002秒〜0.01秒（0.1秒未満）** で即座に応答し、`fetch_live=True` 指定時は Open-Meteo Archive / Forecast API から日次データを取得・再集計してキャッシュを自動更新します（オフライン時はベースラインへ安全にフォールバック）。
3. **`export_parquet=True` による `correlation-discovery-mcp` 自動連携**
- `export_parquet=True` を指定すると、指定キャッシュフォルダ内に標準キー付きの `.parquet` ファイル（`japan_climate_environment_stats.parquet`）を即座に出力します。
- これにより、[`correlation-discovery-mcp`](https://github.com/japan-opendata-lab/correlation-discovery-mcp) が気象データも自動的に相関スキャン対象に取り込み、160以上の公的統計データセットとの相関係数 ($r$値) や回帰外れ値を0.2秒で一括算出できます。
4. **厳格なセキュリティ＆サンドボックス設計**
- **SSRF防止ホワイトリスト**: 外部通信先は HTTPS の `api.open-meteo.com` および `archive-api.open-meteo.com` のみに厳格制限し、内部ネットワークや任意ホストへのリクエストを完全拒否します。
- **パストラバーサル完全拒否**: キャッシュや Parquet 出力時は `Path.resolve()` と `relative_to()` により指定ディレクトリ外（`../` や絶対パス）への書き込みを完全に拒否し、ファイル削除機能は一切持ちません。
- **プロンプトインジェクション対策**: 外部テキストは制御トークンを除去した上で `<untrusted_data>...</untrusted_data>` 境界タグにより無害化します。
---
### 📊 `japan-data-mcp` / `correlation-discovery-mcp` とのクロス分析事例
LM Studio（`Qwen3-8B` 等）や Claude Desktop で以下の3つの MCP を同時登録すると、自然環境×社会経済データの高度なクロス分析がプロンプト1つで完結します。
- **事例1：年間日照時間 × 再生可能エネルギー（太陽光発電）導入量・地価の相関検証**
1. `get_climate_environment_stats(location="all_prefectures", year=2024, export_parquet=True)` を実行し、全47都道府県の気象統計 Parquet を出力（日照時間トップ：山梨県 `2,225.8h`、高知県 `2,168.4h`、宮崎県 `2,154.2h`、静岡県 `2,145.0h`、群馬県 `2,158.4h`）。
2. `correlation-discovery-mcp` の `discover_correlations(mode="find_drivers", target_table="japan_climate_environment_stats", target_column="annual_sunshine_hours", join_key="prefecture")` を実行し、日照時間や冬場の寒暖差と強い相関を持つ社会経済指標（太陽光発電設備容量、空き家率、農業産出額など）を0.1秒でランキング抽出。
- **事例2：冬場の寒暖差・冬日数 × 空き家率・人口動態・医療インフラの要因分析**
1. `winter_temp_range_c`（冬場の寒暖差）や `frost_winter_days`（冬日数）と、`vacant_houses`（空き家率）や `medical`（病院・病床数）を `municipality_code` / `prefecture` キーで結合し、寒冷地や内陸盆地における住宅・医療課題を定量検証。
2. 回帰直線から大きく外れた自治体（異常値・外れ値）を特定し、`japan-data-mcp` の `search_japan_official_data` で当該自治体の個別施設・行政調達データを深掘り調査。
---
### 🛠 セットアップと LM Studio 登録方法
#### 1. インストールとテスト実行
```bash
git clone https://github.com/japan-opendata-lab/japan-climate-stats-mcp.git
cd japan-climate-stats-mcp
pip install -e ".[dev]"
pytest -v
```
#### 2. LM Studio (`~/.lmstudio/mcp.json`) への登録例
```json
{
"mcpServers": {
"japan-climate-stats-mcp": {
"command": "python",
"args": [
"-X",
"utf8",
"./oss_mcp/japan-climate-stats-mcp/server.py"
],
"env": {
"PYTHONIOENCODING": "utf-8",
"CLIMATE_CACHE_DIR": "./oss_mcp/japan-climate-stats-mcp/.cache",
"CLIMATE_EXPORT_DIR": "./oss_mcp/japan-climate-stats-mcp/.cache"
}
}
}
}
```
---
### 🌐 関連エコシステム（Japan Open Data Lab）
- **[`correlation-discovery-mcp`](https://github.com/japan-opendata-lab/correlation-discovery-mcp)**: あらゆる DuckDB / Parquet / CSV データから相関係数 ($r$値)・要因ランキング・回帰外れ値を0.2秒で一括算出する統計探索 MCP サーバー
- **[`japan-data-mcp`](https://github.com/japan-opendata-lab/japan-data-mcp)**: 日本の公的オープンデータ（全162データセット・1,150万件超）を自然言語・標準フィルタ・SQLで検索できる公式 MCP サーバー
- **[`japan-official-data-megabank`](https://github.com/japan-opendata-lab/japan-official-data-megabank)**: 公式 Python SDK ＆ スターターキット
- **[RapidAPI Hub — Japan Open Data Lab](https://rapidapi.com/organization/japan-opendata-lab)**: クラウド API サブスクリプション（無料 BASIC プランあり）
- **[Hugging Face Datasets](https://huggingface.co/datasets/japan-opendata-lab/japan-official-data-megabank)**: サンプル Parquet データセット公開ページ
---
## License
MIT License — Copyright (c) 2026 Japan Open Data Lab (`japan.opendata.lab@gmail.com`)
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo issues