jp-data-mcp — Japanese Public Business Data for AI Agents
A free, open-source MCP 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.
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),
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+.
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, no explicit install step:
uv run --directory /path/to/jp-data-mcp src/server.py
Claude Desktop / MCP client config (stdio)
{
"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.
Local HTTP mode (optional)
python src/server.py --http # streamable-http on 127.0.0.1:8765 (localhost only)
Test
python test_client.py
Data sources & licenses
| Data | Source | Terms |
|---|---|---|
| Corporate registry | 国税庁 法人番号システム Web-API v4 (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 (bank list bundled; branch files fetched on demand) | MIT License |
| National holidays | 内閣府 国民の祝日 CSV (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.