Skip to main content
Glama

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.

Related MCP server: kaisha-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

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

Local review

See the local tool walkthrough for a synthetic example and test scope.

Available Tools

8 tools
is_japan_holidayA

Check whether a date (YYYY-MM-DD) is a Japanese national holiday.

Inputs: day (required). Returns: object

japan_holidaysB

List Japanese national holidays for a year (official Cabinet Office syukujitsu.csv, bundled).

Inputs: year (required). Returns: object

lookup_bankA

Look up a Japanese bank by its 4-digit zengin bank code (統一金融機関コード). Returns name / kana / hiragana / romaji.

Inputs: bank_code (required). Returns: object

lookup_branchA

Look up a bank branch by 4-digit bank code + 3-digit branch code (支店コード). Branch data is lazily fetched from the public zengin-code dataset and cached locally.

Inputs: bank_code (required), branch_code (required). Returns: object

lookup_corporate_numberA

Enrich a 13-digit corporate number with registry data (name, address, kind, dates). Uses the NTA 法人番号 Web-API when NTA_APP_ID is set; otherwise falls back to bundled SYNTHETIC sample data (clearly tagged).

Inputs: number (required). Returns: object

search_banksA

Search Japanese banks by name fragment (kanji / kana / hiragana / romaji all matched). Returns zengin codes + names.

Inputs: query (required), max_results. Returns: object

search_corporations_by_nameA

Search corporations by (partial) name. Live NTA Web-API when NTA_APP_ID is set; otherwise searches the bundled SYNTHETIC sample set.

Inputs: name (required), max_results. Returns: object

validate_corporate_numberA

Validate a 13-digit Japanese corporate number (法人番号) offline: format + official NTA check-digit formula. Does NOT confirm the company exists in the registry (use lookup_corporate_number for that).

Inputs: number (required). Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 8 tools

    Disambiguation5/5

    Each tool targets a distinct resource and action: corporate number validation vs enrichment vs search, bank lookup vs search, branch lookup, and holiday list vs date check. The validate tool explicitly points to lookup for registry confirmation, eliminating any ambiguity.

    Naming Consistency4/5

    Six of eight tools follow a consistent verb_noun pattern (lookup_bank, search_banks, lookup_branch, etc.), but the holiday tools deviate with japan_holidays (a noun) and is_japan_holiday (is_ prefix). Minor pluralization inconsistency (search_banks vs lookup_bank) is acceptable.

    Tool Count5/5

    Eight tools is well-scoped for a Japan data server covering corporate registry, banking, and holidays. Each tool serves a distinct purpose and there is no redundancy.

    Completeness5/5

    The corporate domain has validate, lookup, and search; banking has bank/branch lookup plus search; holidays have list and check. Workflows like search-to-validate-to-lookup are supported, and there are no obvious gaps or dead ends.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      B
      maintenance
      MCP server for the Japan National Tax Agency Corporate Number API, enabling corporate number lookup and search via local AI clients.
      3
      1
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server for the Kaisha API, providing official Japanese company-registry data including corporate numbers and qualified invoice registrations, with pay-per-call via USDC micropayments.
      MIT