JP Data (Japanese Public Business Data)
Japanese open-data MCP server: corporate-number validation, zengin bank codes, national holidays
Open source Open in the app JSON README (API)
About
Japanese open-data MCP server: corporate-number validation, zengin bank codes, national holidays
Details
- Kind
- MCP servers
- Topic
- Finance & crypto
- Publisher
- kimotostudio
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.1.0
- Last push
- 2026-08-05T03:37:57Z
- Repository state
- ativo
- Language
- Python
- License
- MIT
- Added
- 2026-08-29 04:00:20
- Updated
- 2026-08-29 04:00:20
- Origin id
io.github.kimotostudio/jp-data-mcp
README
# jp-data-mcp — Japanese Public Business Data for AI Agents
A free, open-source [MCP](https://modelcontextprotocol.io) server that gives AI
agents the Japanese business-data primitives they most often need:
- **Corporate numbers (法人番号)** — offline check-digit validation and, with a
(free) NTA application ID, live registry enrichment from the National Tax
Agency 法人番号 Web-API: registered name, address, entity kind, dates.
- **Zengin bank / branch codes (統一金融機関コード・支店コード)** — the codes that
describe a Japanese domestic bank transfer, with kana / hiragana / romaji.
- **Japanese national holidays** — official Cabinet Office holiday data, bundled.
It runs entirely on your machine. No account, no API key of ours, no payments,
no telemetry — usage is not logged or reported anywhere.
<!-- mcp-name: io.github.kimotostudio/jp-data-mcp -->
## Tools
| Tool | What it does |
|---|---|
| `validate_corporate_number` | Offline format + official NTA check-digit validation of a 13-digit 法人番号 (full-width input tolerated). Does **not** confirm the company exists. |
| `lookup_corporate_number` | Registry enrichment for a corporate number (live NTA Web-API when `NTA_APP_ID` is set; otherwise a clearly-tagged synthetic fallback — see below). |
| `search_corporations_by_name` | Search corporations by (partial) name (live NTA Web-API when `NTA_APP_ID` is set). |
| `lookup_bank` | Bank by 4-digit zengin bank code → name / kana / hiragana / romaji. |
| `search_banks` | Search banks by name fragment (kanji / kana / hiragana / romaji). |
| `lookup_branch` | Branch by bank code + 3-digit branch code (branch data lazily fetched from the public zengin-code dataset and cached locally). |
| `japan_holidays` | All Japanese national holidays for a given year. |
| `is_japan_holiday` | Whether a `YYYY-MM-DD` date is a national holiday. |
## Important: the SYNTHETIC_SAMPLE fallback
Live corporate-registry data requires a **free** NTA Web-API application ID
(register at the [国税庁 法人番号システム Web-API site](https://www.houjin-bangou.nta.go.jp/webapi/)),
supplied via the `NTA_APP_ID` environment variable.
**Without `NTA_APP_ID`**, `lookup_corporate_number` and
`search_corporations_by_name` fall back to a tiny bundled **synthetic** sample
set. These records are fabricated for testing, do **not** correspond to real
companies, and every one of them is tagged `"source": "SYNTHETIC_SAMPLE"` plus
an explanatory `note` in the response — they can never be mistaken for real
registry data. Check-digit validation and the bank/holiday tools do not need
any key and always use real data.
Known limitation: the NTA v4 CSV column mapping is written from the published
spec but has not yet been verified against a live API response. If you find a
misaligned field, please open an issue.
## Install & run
Requires Python 3.11+.
```bash
git clone https://github.com/kimotostudio/jp-data-mcp.git
cd jp-data-mcp
pip install fastmcp httpx # or: uv sync
python src/server.py # stdio MCP server
```
Or with [uv](https://docs.astral.sh/uv/), no explicit install step:
```bash
uv run --directory /path/to/jp-data-mcp src/server.py
```
### Claude Desktop / MCP client config (stdio)
```json
{
"mcpServers": {
"jp-data": {
"command": "uv",
"args": ["run", "--directory", "/path/to/jp-data-mcp", "src/server.py"],
"env": { "NTA_APP_ID": "your-nta-app-id (optional)" }
}
}
}
```
An `.mcpb` bundle (usable with MCPB-aware clients) is attached to each
[GitHub release](https://github.com/kimotostudio/jp-data-mcp/releases).
### Local HTTP mode (optional)
```bash
python src/server.py --http # streamable-http on 127.0.0.1:8765 (localhost only)
```
## Test
```bash
python test_client.py
```
## Data sources & licenses
| Data | Source | Terms |
|---|---|---|
| Corporate registry | [国税庁 法人番号システム Web-API v4](https://www.houjin-bangou.nta.go.jp/webapi/) (live, only when you configure your own `NTA_APP_ID`) | NTA Web-API terms of use apply to your usage |
| Check-digit formula | Official NTA specification (implemented offline) | — |
| Bank / branch codes | [zengin-code/source-data](https://github.com/zengin-code/source-data) (bank list bundled; branch files fetched on demand) | MIT License |
| National holidays | [内閣府 国民の祝日 CSV](https://www8.cao.go.jp/chosei/shukujitsu/gaiyou.html) (bundled, converted to UTF-8) | Japanese government open data |
| Synthetic corporate samples | Generated for this project (valid check digits, fictional companies) | MIT (part of this repo) |
## Disclaimer
This project is not affiliated with or endorsed by the National Tax Agency,
the Japanese Bankers Association, the zengin-code project, or the Cabinet
Office. Data is provided as-is with no warranty of accuracy or completeness —
verify against official sources before relying on it for legal, tax,
accounting, or payment decisions. Bundled datasets are snapshots and may lag
the official sources.
## License
[MIT](LICENSE)