jp-data-mcp

# jp-data-mcp — Japanese Public Business Data for AI Agents

A free, open-source [MCP](https://modelcontextprotocol.io) 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.

<!-- mcp-name: io.github.kimotostudio/jp-data-mcp -->

## 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](https://www.houjin-bangou.nta.go.jp/webapi/)),
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](https://docs.astral.sh/uv/), no explicit install step:

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

### Claude Desktop / MCP client config (stdio)

```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](https://github.com/kimotostudio/jp-data-mcp/releases).

### 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](https://www.houjin-bangou.nta.go.jp/webapi/) (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](https://github.com/zengin-code/source-data) (bank list bundled; branch files fetched on demand) | MIT License |
| National holidays | [内閣府 国民の祝日 CSV](https://www8.cao.go.jp/chosei/shukujitsu/gaiyou.html) (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](LICENSE)