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

Related MCP server: houjin-bangou-api-mcp

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

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