# jp-verify-mcp

<!-- mcp-name: xyz.obolpay/jp-verify -->

An [MCP](https://modelcontextprotocol.io) server for [JP-Verify](https://jp-verify.obolpay.xyz), the
English-first API that verifies Japanese companies: qualified-invoice registration numbers
(T-numbers), Corporate Numbers (法人番号), English names and major shareholders.

It is a thin client. Each tool call is one HTTPS request to JP-Verify's public API at
`https://jp-verify.obolpay.xyz`. The package holds no register data and contacts no other site; it
downloads nothing from the National Tax Agency or from EDINET.

## Tools

| Tool | JP-Verify endpoint | Returns |
|---|---|---|
| `verify_japanese_company` | `GET /v1/verify` | Registration status and dates, Corporate Number, Japanese name and address, English name and address (labelled official or machine-romanised) |
| `verify_japanese_companies_batch` | `POST /v1/verify` | The same for many numbers: up to 100 per call on the sandbox and Starter keys, 500 on Growth, 1,000 on Reseller. Malformed numbers are listed under `invalid` and not charged |
| `get_major_shareholders` | `GET /v1/shareholders` | The 「大株主の状況」 (major shareholders) table from a company's securities report on EDINET, or a `no_public_disclosure` statement. Optional `as_of` (YYYY-MM-DD) |
| `find_japanese_company_by_name` | `GET /v1/resolve` | Candidate Corporate Numbers for a company name (rule-based exact matching, not fuzzy search) |

All four are read-only. Each answered call (HTTP 200) is one metered lookup on your JP-Verify plan;
the batch tool counts one per well-formed number. `verify_japanese_company` and
`get_major_shareholders` reject a number that fails JP-Verify's own format or check-digit rule
locally, without a call; the batch tool sends the list as given and JP-Verify lists such numbers
under `invalid`, free of charge.

Every result has two parts:

- `jp_verify_response`: JP-Verify's answer exactly as sent, including `data_as_of`, notes,
  disclaimers and the `attribution` strings;
- `metadata`: the endpoint, the HTTP status, whether an API key or the key-less sandbox was used,
  the quota headers (`limit`, `remaining`, `resets_at`) and where the data comes from.

HTTP errors (400, 401, 404, 429, 503, 5xx) and network failures come back as tool errors with a
one-line explanation. JP-Verify does not charge for 400, 401, 404, 429 or 503 answers.

## Install and run

Requires Python 3.10 or later.

```bash
uvx jp-verify-mcp                # or: pip install jp-verify-mcp && jp-verify-mcp
```

From a source checkout: `pip install .`, then `jp-verify-mcp`.

### stdio (default)

For Claude Desktop, Claude Code (`.mcp.json`), Cursor and other clients that start a local server:

```json
{
  "mcpServers": {
    "jp-verify": {
      "command": "uvx",
      "args": ["jp-verify-mcp"],
      "env": { "JPVERIFY_API_KEY": "your key (optional)" }
    }
  }
}
```

Leave out `env` to use the key-less sandbox.

### Streamable HTTP

```bash
jp-verify-mcp --transport streamable-http --host 127.0.0.1 --port 8000
# endpoint: http://127.0.0.1:8000/mcp  (stateless, JSON responses)
```

- A client may send its own key in an `X-API-Key` header. It is forwarded to JP-Verify for that
  call only and takes precedence over `JPVERIFY_API_KEY`.
- A loopback bind gets DNS-rebinding protection automatically. For a public host name pass
  `--allowed-host your.host.name` (repeatable).
- On a non-loopback address the server refuses to start while `JPVERIFY_API_KEY` is set, because
  every caller without its own key would use it. Pass `--allow-shared-key` if that is intended.
- The sandbox allowance is per IP address, so key-less callers of a hosted endpoint share the
  host's allowance.

### Configuration

| Variable | Default | Meaning |
|---|---|---|
| `JPVERIFY_API_KEY` | unset | Your JP-Verify API key, sent as `X-API-Key`. Unset: the key-less sandbox |
| `JPVERIFY_BASE_URL` | `https://jp-verify.obolpay.xyz` | API origin. Plain `http://` is accepted only for localhost |
| `JPVERIFY_TIMEOUT` | `20` | Seconds per request (at most 120) |

Other options: `jp-verify-mcp --help`.

## Keys and plans

- Without a key, JP-Verify's key-less sandbox answers. It is limited per IP address per day
  (JP-Verify documents 50 requests a day, as of 2026-10-07) and JP-Verify may change or end it
  (its Terms, Article 4).
- Paid plans and their prices are published on JP-Verify's legal notice:
  https://jp-verify.obolpay.xyz/legal. For a key, see https://jp-verify.obolpay.xyz or write to
  yanagithefirst11@gmail.com.

## Data, sources and attribution

- Registration status, Corporate Number and Japanese name and address come from data published by
  Japan's National Tax Agency (国税庁): 国税庁適格請求書発行事業者公表サイト (qualified invoice
  issuers) and 国税庁法人番号公表サイト (Corporate Numbers), mirrored and processed by JP-Verify.
  They are not produced or guaranteed by the National Tax Agency.
- English names: `official-en` where the company filed an English name with the Corporate Number
  register; otherwise `generated`, a machine romanisation that is not authoritative. Most
  companies have not filed one.
- Sole proprietors: number, status and dates only. No name or address is returned.
- Major shareholders: the 「大株主の状況」 tables companies file on the FSA's EDINET, extracted by
  JP-Verify. Organisations are named; every other holder, including every individual, is
  reported without a name, normally as an aggregate (always on the sandbox). Only companies that
  file a 有価証券報告書 or 半期報告書 publish this table; for any other company JP-Verify returns
  `no_public_disclosure`, a statement of why nothing is published (not a claim that the company
  has no shareholders). Some filers may show `not_yet_available` while JP-Verify's ingest catches
  up. JP-Verify switches this route on separately (its `/health` reports
  `major_shareholders.enabled`); until then the tool answers `route_not_enabled`.
- JP-Verify may add the FSA's EDINET code list (PDL1.0) and GLEIF LEI data (CC0 1.0) to a result.
- When you republish data from a response, keep its `attribution` strings and `*_register`
  blocks (JP-Verify Terms, Article 5).
- These are register facts as of the dates each response states. They are not tax, legal,
  investment or ownership advice. JP-Verify answers 503 rather than serve data older than its
  freshness window.

## Privacy

The server sends JP-Verify only what a tool is asked about (numbers, a name, a date) and the API
key, if any. It stores nothing, keeps no cache, never retries a call and adds no logging of its
own; at the default log level (WARNING) request contents are not logged. JP-Verify's privacy
statement: https://jp-verify.obolpay.xyz/v1/privacy. Terms: https://jp-verify.obolpay.xyz/terms.

## Development

```bash
python3 -m venv .venv && .venv/bin/pip install -e '.[test]'
.venv/bin/python -m pytest
```

The tests never reach JP-Verify: HTTP is mocked, or answered by a stand-in on 127.0.0.1.

## Company and contact

Yanagi the First Co., Ltd. (株式会社ヤナギtheファースト) · yanagithefirst11@gmail.com ·
https://jp-verify.obolpay.xyz

## License

MIT, for this client. Use of the JP-Verify service is governed by its Terms of Service.

## Registry

Official MCP Registry name: `xyz.obolpay/jp-verify`. Source: https://github.com/Hiroshi-Ichiyanagi/jp-verify-mcp