# boj-jstat-mcp

[日本銀行 時系列統計データ検索サイト](https://www.stat-search.boj.or.jp/)のAPI機能を利用するMCP（Model Context Protocol）サーバーです。

金利、マネーサプライ、為替レート、短観、国際収支、物価指数など、40以上の日銀統計データベースにClaude/CodexなどのAIアシスタントから直接アクセスできます。

## クイックスタート

`git clone` なしでそのまま使えます。`npx -y boj-jstat-mcp@latest` を指定すると npm から取得して起動できます。

> 注意（2026-02-25時点）: `boj-mcp@latest` は別プロジェクト（solved.ac向け）であり、このリポジトリの日銀MCPではありません。

### Claude Desktop

`claude_desktop_config.json` に以下を追加：

```json
{
  "mcpServers": {
    "boj": {
      "command": "npx",
      "args": ["-y", "boj-jstat-mcp@latest"]
    }
  }
}
```

### Claude Code

追加:

```bash
claude mcp add boj -- npx -y boj-jstat-mcp@latest
```

確認:

```bash
claude mcp list
```

削除:

```bash
claude mcp remove boj
```

### Codex CLI

追加:

```bash
codex mcp add boj -- npx -y boj-jstat-mcp@latest
```

確認:

```bash
codex mcp list
codex mcp get boj
```

削除:

```bash
codex mcp remove boj
```

## 使い方（推奨フロー）

1. `boj_list_databases` でDB候補を絞る
2. `boj_get_metadata` を `limit=20-50` 程度で呼び、系列コード/レイヤーを特定
3. `boj_get_data_code` または `boj_get_data_layer` で本取得
4. `NEXTPOSITION` が返ったら `startPosition` でページング

## 使用例

**物価関連のDBを探す：**
> 「物価に関する日銀のデータベースを一覧表示して」

**短観DIデータを取得：**
> 「2024年第1四半期から2025年第4四半期までの短観・大企業製造業の業況判断DIを取得して」

**為替レートを確認：**
> 「2025年12月のドル円為替レートデータを見せて」

**国際収支を参照：**
> 「2025年1月の国際収支統計から経常収支を取得して」

## アクセス可能なデータベース一覧

### 1. 金利（預金・貸出関連）

| DBコード | 説明 |
| -------- | ---- |
| IR01 | 基準割引率および基準貸付利率（従来「公定歩合」として掲載されていたもの）の推移 |
| IR02 | 預金種類別店頭表示金利の平均年利率等 |
| IR03 | 定期預金の預入期間別平均金利 |
| IR04 | 貸出約定平均金利 |

### 2. マーケット関連

| DBコード | 説明 |
| -------- | ---- |
| FM01 | 無担保コールO/N物レート（毎営業日） |
| FM02 | 短期金融市場金利 |
| FM03 | 短期金融市場残高 |
| FM04 | コール市場残高 |
| FM05 | 公社債発行・償還および現存額 |
| FM06 | 公社債消化状況（利付国債） |
| FM07 | （参考）国債窓口販売額・窓口販売率（2004年1月まで） |
| FM08 | 外国為替市況 |
| FM09 | 実効為替レート |

### 3. 決済関連

| DBコード | 説明 |
| -------- | ---- |
| PS01 | 各種決済 |
| PS02 | フェイルの発生状況 |

### 4. 預金・マネー・貸出

| DBコード | 説明 |
| -------- | ---- |
| MD01 | マネタリーベース |
| MD02 | マネーストック |
| MD03 | マネタリーサーベイ |
| MD04 | （参考）マネーサプライ（M2+CD）増減と信用面の対応 |
| MD05 | 通貨流通高 |
| MD06 | 日銀当座預金増減要因と金融調節（実績） |
| MD07 | 準備預金額 |
| MD08 | 業態別の日銀当座預金残高 |
| MD09 | マネタリーベースと日本銀行の取引 |
| MD10 | 預金者別預金 |
| MD11 | 預金・現金・貸出金 |
| MD12 | 都道府県別預金・現金・貸出金 |
| MD13 | 貸出・預金動向 |
| MD14 | 定期預金の残高および新規受入高 |
| LA01 | 貸出先別貸出金 |
| LA02 | 日本銀行貸出 |
| LA03 | その他貸出残高 |
| LA04 | コミットメントライン契約額、利用額 |
| LA05 | 主要銀行貸出動向アンケート調査 |

### 5. 金融機関バランスシート

| DBコード | 説明 |
| -------- | ---- |
| BS01 | 日本銀行勘定 |
| BS02 | 民間金融機関の資産・負債 |

### 6. 資金循環

| DBコード | 説明 |
| -------- | ---- |
| FF | 資金循環 |

### 7. その他の日本銀行関連

| DBコード | 説明 |
| -------- | ---- |
| OB01 | 日本銀行の対政府取引 |
| OB02 | 日本銀行が受入れている担保の残高 |

### 8. 短観

| DBコード | 説明 |
| -------- | ---- |
| CO | 短観 |

### 9. 物価

| DBコード | 説明 |
| -------- | ---- |
| PR01 | 企業物価指数 |
| PR02 | 企業向けサービス価格指数 |
| PR03 | 製造業部門別投入・産出物価指数 |
| PR04 | ＜サテライト指数＞最終需要・中間需要物価指数 |

### 10. 財政関連

| DBコード | 説明 |
| -------- | ---- |
| PF01 | 財政資金収支 |
| PF02 | 政府債務 |

### 11. 国際収支・BIS関連

| DBコード | 説明 |
| -------- | ---- |
| BP01 | 国際収支統計 |
| BIS | BIS国際資金取引統計および国際与信統計の日本分集計結果 |
| DER | デリバティブ取引に関する定例市場報告 |

### 12. その他

| DBコード | 説明 |
| -------- | ---- |
| OT | その他 |

## ツール一覧

### `boj_list_databases` — DB一覧表示

利用可能な日銀統計データベースの一覧を表示します。APIコール不要（静的データ）。

| パラメータ | 必須 | 説明                                |
| ---------- | ---- | ----------------------------------- |
| `category` | いいえ | カテゴリでフィルタ                  |
| `search`   | いいえ | コードまたは名前で検索              |

### `boj_get_metadata` — メタデータ取得

データベースのメタデータ（系列コード、名称、単位、期種、階層構造）を取得します。
返却には `SERIES_CODE` を持つ行のみを表示し、`boj_get_data_code` で使えない見出し行は除外します。

| パラメータ | 必須 | 説明                         |
| ---------- | ---- | ---------------------------- |
| `db`       | はい | DBコード（例：`CO`）         |
| `lang`     | いいえ | `jp`（デフォルト）または `en` |
| `limit`    | いいえ | 返却件数上限（デフォルト200、最大1000） |

### `boj_get_data_code` — 系列コード指定データ取得

系列コードを指定して時系列データを取得します。1リクエストあたり最大250系列/60,000データポイント。
`code` は必ず `boj_get_metadata` で取得した `SERIES_CODE` をそのまま指定してください（DB接頭辞や引用符区切りの旧形式は不可）。無効コード時は近い候補を提示し、近似一致が十分高い場合は自動補正して再試行します。

| パラメータ      | 必須 | 説明                                           |
| --------------- | ---- | ---------------------------------------------- |
| `db`            | はい | DBコード                                       |
| `code`          | はい | カンマ区切りの系列コード（同一期種のみ）       |
| `lang`          | いいえ | `jp`（デフォルト）または `en`                   |
| `startDate`     | いいえ | 開始期（形式は期種に依存）                     |
| `endDate`       | いいえ | 終了期                                         |
| `startPosition` | いいえ | ページネーション（前回のNEXTPOSITION値）       |

### `boj_get_data_layer` — 階層指定データ取得

階層構造を指定して時系列データを取得します。ワイルドカード `*` 対応。最大1,250系列/60,000データポイント。

| パラメータ      | 必須 | 説明                                                    |
| --------------- | ---- | ------------------------------------------------------- |
| `db`            | はい | DBコード                                                |
| `layer`         | はい | カンマ区切りの階層値（例：`1,1,1`）、`*` で全指定       |
| `frequency`     | はい | `CY`, `FY`, `CH`, `FH`, `Q`, `M`, `W`, `D`             |
| `lang`          | いいえ | `jp`（デフォルト）または `en`                            |
| `startDate`     | いいえ | 開始期                                                  |
| `endDate`       | いいえ | 終了期                                                  |
| `startPosition` | いいえ | ページネーション（前回のNEXTPOSITION値）                |

## 日付パラメータの仕様（重要）

- BOJ API の仕様上、`startDate` / `endDate` は期種単位の指定です。
- `YYYY-MM-DD` と `YYYYMMDD` を渡した場合、サーバー側で期種フォーマットへ正規化します。
- `D`（日次）/`W`（週次）系列でも、BOJ API には `YYYYMM` 形式で問い合わせます（返却データ自体は日付単位）。

## レート制限

BOJの「高頻度アクセスは避けてください」というガイドラインに準拠するため、トークンバケット方式のレートリミッター（容量5、毎秒1トークン補充）を内蔵しています。並列リクエスト時も内部キューで制御し、過剰送信を防ぎます。

## 動作要件

- Node.js 18.0.0以上

## クレジット

このサービスは、日本銀行時系列統計データ検索サイトの API 機能を使用しています。サービスの内容は日本銀行によって保証されたものではありません。