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+.

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, no explicit install step:

bash

uv run --directory /path/to/jp-data-mcp src/server.py

Claude Desktop / MCP client config (stdio)

config.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.

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 (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.

License

MIT