JP Data (Japanese Public Business Data)

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)

免責事項

このプロジェクトは、国税庁、全国銀行協会、全銀コードプロジェクト、または内閣府とは一切関係がなく、これらから承認も受けていません。 データは現状のまま提供され、正確性や完全性について一切保証しません。法務、税務、会計、または支払いに関する判断に利用する前に、必ず公式情報源で確認してください。 同梱されているデータセットは特定時点のものであり、公式情報源の更新に追いついていない場合があります。

ライセンス

MIT