jp-data-mcp
A free, local MCP server that gives AI agents Japanese business-data primitives: corporate numbers, zengin bank/branch codes, and national holidays.
Validate corporate numbers offline (
validate_corporate_number): format + official NTA check-digit check on a 13-digit 法人番号 (full-width tolerated); does not confirm the company exists.Enrich or search corporate registry (
lookup_corporate_number,search_corporations_by_name): name, address, entity kind, and dates via the live NTA Web-API whenNTA_APP_IDis set; otherwise a clearly taggedSYNTHETIC_SAMPLEfallback.Look up banks (
lookup_bank,search_banks): 4-digit zengin bank codes or name fragments in kanji/kana/hiragana/romaji, returning codes plus names and readings.Look up branches (
lookup_branch): bank code + 3-digit branch code, with branch data lazily fetched from the public zengin-code dataset and cached locally.Work with Japanese holidays (
japan_holidays,is_japan_holiday): list all national holidays for a year, or test whether aYYYY-MM-DDdate is a holiday, from bundled Cabinet Office data.Run fully locally: stdio MCP server (or optional localhost-only HTTP mode), no account, no telemetry; only the NTA tools need your own free application ID.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@jp-data-mcp What are Japan's national holidays in 2025?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 |
| Offline format + official NTA check-digit validation of a 13-digit 法人番号 (full-width input tolerated). Does not confirm the company exists. |
| Registry enrichment for a corporate number (live NTA Web-API when |
| Search corporations by (partial) name (live NTA Web-API when |
| Bank by 4-digit zengin bank code → name / kana / hiragana / romaji. |
| Search banks by name fragment (kanji / kana / hiragana / romaji). |
| Branch by bank code + 3-digit branch code (branch data lazily fetched from the public zengin-code dataset and cached locally). |
| All Japanese national holidays for a given year. |
| Whether a |
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 serverOr with uv, no explicit install step:
uv run --directory /path/to/jp-data-mcp src/server.pyClaude 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.pyData sources & licenses
Data | Source | Terms |
Corporate registry | 国税庁 法人番号システム Web-API v4 (live, only when you configure your own | 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
Local review
See the local tool walkthrough for a synthetic example and test scope.
Available Tools
8 toolsis_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
Scored across 8 tools
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.
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.
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.
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
Related MCP Connectors
MCP server for Japan geodata: cadastral lot numbers (chiban) and reverse geocoding, for AI agents.
Hosted MCP server for live public-data APIs and Skills for AI agents.
Japanese law, corporation & statistics data as MCP, normalized to English with source attribution.
CompanyLens is a remote MCP server giving AI agents instant access to official company registry data across 19 jurisdictions in Europe, the Americas, and Asia-Pacific. Eighteen read-only tools let you search companies and people, look up officers and beneficial owners, map corporate networks through shared directors, screen names against the UK disqualified directors register, find every company at a registered address, and pull filing history — all from a single connector. Visit our website: https://companylens.io
Related MCP Servers
- AlicenseBqualityBmaintenanceMCP server for the Japan National Tax Agency Corporate Number API, enabling corporate number lookup and search via local AI clients.31MIT
- AlicenseNot gradedqualityDmaintenanceMCP 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
- AlicenseAqualityDmaintenanceMCP server providing AI agents with access to Japanese data APIs (address, furigana, transit, diet, holiday, weather, houjin) via a pay-per-use x402 payment protocol.2862 npm2Apache 2.0
- AlicenseAqualityDmaintenanceAn MCP server that validates Japanese corporate numbers and invoice registration numbers, and normalizes/matches company names across notation variants.737 npmMIT