# boj-stats-mcp

日本銀行 時系列統計の公式APIを参照する読み取り専用のMCPサーバーです。Python 3.12以上とuv（0.13.4で検証）を使います。上流APIのキー設定は不要です。

## MCPクライアント設定

GitHubリポジトリへのアクセス権がある環境でクローンします。

```sh
git clone https://github.com/koizumikento/boj-stats-mcp.git
cd boj-stats-mcp
uv sync --locked
```

クライアントの設定に、クローン先の絶対パスを指定します。

```json
{
  "mcpServers": {
    "boj-stats-mcp": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/boj-stats-mcp", "run", "--locked", "boj-stats-mcp"]
    }
  }
}
```

## ツール

| ツール | 用途 |
| --- | --- |
| `search_series` | DB内の系列を系列名・系列コードで検索 |
| `get_series_data` | 系列コードと期間で時系列を取得 |

DB名と系列コードでデータを特定します。初版は1回の呼び出しで1系列を取得します。期間の書式は対象系列の期種に合わせて指定してください。

## CLI

```sh
uv run boj-stats-mcp search-series --database FM08 --query "ドル" --limit 1
uv run boj-stats-mcp get-series-data --database FM08 --series-code FXERD04 --start-period 202501 --end-period 202501
```

結果は標準出力にUTF-8のJSONで出力します。コマンドの引数は `uv run boj-stats-mcp search-series --help` で確認できます。

## Pythonライブラリ

パッケージをインストールしたPython環境で、下記の非同期関数を直接呼び出せます。

```python
import asyncio

from boj_stats_mcp import search_series

result = asyncio.run(search_series(database="FM08", query="ドル", limit=1))
print(result)
```

公開関数 `search_series`、`get_series_data` を利用できます。イベントループがある環境では、関数を直接 `await` します。

## 出典と利用条件

コードはMIT Licenseです。取得するデータの権利と利用条件は、API提供元と各データ提供機関の定めに従います。[公式API仕様](https://www.stat-search.boj.or.jp/info/api_manual.pdf) · [利用案内](https://www.stat-search.boj.or.jp/info/nme_aphelp.html)

## 開発

```sh
uv sync --locked
uv run ruff check .
uv run ty check
uv run pytest
uv build
```