jp-verify-mcp
An MCP server for JP-Verify, 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.
| 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.
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:
{
"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
jp-verify-mcp --transport streamable-http --host 127.0.0.1 --port 8000
- 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
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
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.
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