boj-mcp 0.2.1
BOJ statistics MCP tool - Access BOJ statistics via the official REST API
Requires Python: >=3.10
Keywords: bank-of-japan, boj, japan, macro-economics, mcp, statistics

# boj-mcp

[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: Apache-2.0](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
[![PyPI](https://img.shields.io/pypi/v/boj-mcp.svg)](https://pypi.org/project/boj-mcp/)

Bank of Japan statistics MCP tool — powered by the official BOJ REST API.

## What is this?

**boj-mcp** provides instant access to Bank of Japan statistical data via the [official BOJ REST API](https://www.stat-search.boj.or.jp/api/v1/) (launched February 2026).

- **34 databases** covering interest rates, financial markets, prices, TANKAN, flow of funds, and more
- **No API key required** — all data is publicly available
- **MCP server** for AI assistant integration (Claude Desktop, etc.)
- **Python client** for programmatic access
- Part of the [Japan Finance Data Stack](https://github.com/ajtgjmdjp/awesome-japan-finance-data)

## Quick Start

```bash
pip install boj-mcp
# or
uv add boj-mcp
```

### 30-Second Example

```python
import asyncio
from boj_mcp import BojClient

async def main():
    async with BojClient() as client:
        # Search for series
        series = await client.search_series("call rate", db="IR01")
        print(series[0].series_code)  # e.g. "MADR1M"

        # Fetch time series data
        data = await client.get_series_data("IR01", "MADR1M")
        print(data.latest)  # BojObservation(date='202601', value=1.0)

asyncio.run(main())
```

### CLI

```bash
# List all databases
boj-mcp databases

# Search for series
boj-mcp search "call rate"
boj-mcp search "producer price" --db PR01

# Fetch time series data
boj-mcp data IR01 MADR1M
boj-mcp data IR01 MADR1M --start 202001 --end 202601 --format json

# Test connectivity
boj-mcp test

# Start MCP server
boj-mcp serve
```

## MCP Server

Add to Claude Desktop config:

```json
{
  "mcpServers": {
    "boj": {
      "command": "uvx",
      "args": ["boj-mcp", "serve"]
    }
  }
}
```

### Available MCP Tools

| Tool | Description |
|------|-------------|
| `list_databases` | List all 34 available BOJ databases |
| `search_series` | Search for time series by keyword |
| `get_series_data` | Fetch time series data by database + series code |
| `get_database_info` | Browse all series in a database |

## Available Databases

| Code | Description | Category |
|------|-------------|----------|
| IR01 | Basic Discount/Loan Rates and Overnight Call Rates | Interest Rates |
| IR02 | Interest Rates on Deposits and Lending | Interest Rates |
| IR03 | Market Interest Rates | Interest Rates |
| IR04 | International Interest Rates and Financial Indicators | Interest Rates |
| FM01 | Foreign Exchange Rates | Financial Markets |
| FM02 | Stock Price Indexes | Financial Markets |
| FM03–FM09 | Bond, Money Market, Commodities, Derivatives, REITs… | Financial Markets |
| MD01 | Money Stock | Money and Banking |
| MD02–MD14 | Deposits, Loans, Financial Statements… | Money and Banking |
| PR01 | Corporate Goods Price Index (CGPI) | Prices |
| PR02 | Services Producer Price Index (SPPI) | Prices |
| PR03 | Import/Export Price Index | Prices |
| PR04 | Residential Land Prices | Prices |
| CO | TANKAN: Short-term Economic Survey | Surveys |
| FF | Flow of Funds Accounts | Flow of Funds |
| BP01 | Balance of Payments | External Accounts |

## Python API

```python
from boj_mcp import BojClient

async with BojClient() as client:
    # List all databases (no network call)
    dbs = client.list_databases()

    # Browse a database (up to 500 series)
    series = await client.get_metadata("PR01", max_items=50)

    # Search across databases
    results = await client.search_series("yen", db="FM01")

    # Fetch time series with date filter
    data = await client.get_series_data(
        "IR01", "MADR1M",
        start_date="202001",
        end_date="202601",
    )
    for obs in data.observations[-6:]:
        print(f"{obs.date}: {obs.value}%")
```

## Data Attribution

This project uses data from the [Bank of Japan](https://www.boj.or.jp/) (日本銀行).

**Source**: Bank of Japan, Statistical Data ([https://www.stat-search.boj.or.jp/](https://www.stat-search.boj.or.jp/))

> このサービスは、日本銀行時系列統計データ検索サイトのAPI機能を使用しています。サービスの内容は日本銀行によって保証されたものではありません。
>
> This service uses the API of the Bank of Japan's Time-Series Data Search Site. The content of this service is not guaranteed by the Bank of Japan.

> **Disclaimer**: This project is neither officially related to nor endorsed by the Bank of Japan.

## Related Projects

- [edinet-mcp](https://github.com/ajtgjmdjp/edinet-mcp) — EDINET corporate financial data
- [estat-mcp](https://github.com/ajtgjmdjp/estat-mcp) — e-Stat government statistics
- [stockprice-mcp](https://github.com/ajtgjmdjp/stockprice-mcp) — Stock prices & FX rates (Yahoo Finance)
- [awesome-japan-finance-data](https://github.com/ajtgjmdjp/awesome-japan-finance-data) — Japan Finance Data Stack

## License

Apache-2.0

<!-- mcp-name: io.github.ajtgjmdjp/boj-mcp -->