Skip to main content
Glama
mcp-jp-corporate-id

mcp-jp-corporate-id

mcp-jp-corporate-id

日本語版はこちら

An MCP (Model Context Protocol) server that validates and normalizes Japanese corporate numbers (houjin bangou) and qualified invoice issuer registration numbers, and normalizes/matches company names across common notation variants.

No network access is used at all (v1 calls no external APIs). Every check is done with formulas and dictionary data embedded in the code.

Read this first

  • This tool only validates the format of numbers and names. It does NOT verify that a company actually exists, or that an invoice registration is currently valid. For real-world verification, always check the official National Tax Agency sites directly:

  • Never enter a Japanese Individual Number (My Number). A company registration number (12 digits) and an individual My Number (12 digits) have the same length, and this tool cannot distinguish which kind of number it was given. calculate_check_digit always includes a caution about this in its response.

  • This server never logs request input, and validation-error messages never echo back the raw number that was submitted.

Related MCP server: jp-pint-mcp

Tools (7 total)

Tool

Description

validate_corporate_number

Verifies the check digit of a 13-digit corporate number

calculate_check_digit

Computes the check digit for a 12-digit company registration number and derives the 13-digit corporate number

validate_invoice_number

Validates a qualified invoice registration number ("T" + 13 digits)

parse_corporate_number

Breaks down the structure of a corporate number (category, registry office code, organization type, serial number)

normalize_company_name

Normalizes company-name notation (株式会社/(株)/㈱ etc., prefix/suffix placement, legacy kanji forms)

generate_matching_key

Generates a normalized key for company-name deduplication/matching

compare_company_names

Judges whether two company names likely refer to the same entity (likely_different only under a strict, narrow condition; returns "unknown" whenever it cannot tell)

Every tool's response includes the primary sources (sources) behind its logic.

1. validate_corporate_number

Verifies whether the check digit of a 13-digit corporate number is correct. Accepts full-width digits, hyphens, and whitespace, which are normalized before validation. If the normalized length isn't 13 digits, or the check digit doesn't match, the tool returns valid: false rather than throwing.

2. calculate_check_digit

Computes the check digit from a 12-digit company registration number (assigned based on commercial registry records) and derives the 13-digit corporate number. Throws if the normalized input isn't exactly 12 digits (no guessing or zero-padding).

Caution: a 12-digit number could just as easily be a My Number (individual number) as a company registration number. Every response includes a caution field reminding callers never to submit a My Number. If the registry office code portion falls outside the typical range (0100–5000) confirmed from primary sources, a note is added.

3. validate_invoice_number

Validates a qualified invoice registration number ("T" + 13 digits).

  • For numbers held by corporations ("T" + corporate number), the check digit is verified mathematically; a match returns entityType: "corporate".

  • Numbers held by sole proprietors and unincorporated associations are separate 13-digit numbers issued by the NTA that overlap with neither My Number nor any corporate number. The check-digit algorithm for this class of number could not be confirmed as publicly documented within the primary sources reviewed. When the number doesn't match the corporate-number check-digit formula, the tool returns entityType: "individual_or_other", validates format only, and explicitly states that mathematical verification isn't possible in this case.

  • If the input doesn't even match the "T" + 13 digits shape, formatValid: false is returned (not an exception).

4. parse_corporate_number

Verifies the check digit of a 13-digit corporate number and then parses the structure of its 12-digit base number.

  • category: national_organ_legislative / national_organ_administrative / national_organ_judicial / local_government / registered_corporation / unregistered_corporation_or_unincorporated_association / unused_range

  • For registered_corporation, returns registryOfficeCode (4 digits), organizationTypeCode (raw 2 digits), and serialNumber (6 digits).

  • The mapping from the 2-digit organization type code to an actual corporate form (stock company, LLC, etc.) could not be confirmed as a documented numeric code table in the primary sources reviewed (the Commercial Registration Rules define three textual categories but the reviewed article text does not spell out numeric codes for them). The tool therefore returns only the raw 2-digit code with no label — see "Items that could not be verified" below.

5. normalize_company_name

Normalizes company-name notation and separates out the "body name" with the corporate form removed.

  • Converts between major corporate-form notations (株式会社/(株)/(株)/㈱, etc.).

  • Detects whether the corporate form appears as a prefix (株式会社○○) or suffix (○○株式会社).

  • Normalizes full-width/half-width characters and a curated set of legacy/variant kanji forms (e.g. 髙→高, 﨑→崎).

Dictionary limits: only major corporate forms and variant characters are covered. This is not exhaustive of every Japanese corporate form or notation variant; anything not in the dictionary is left unrecognized and stays in the body name as-is.

6. generate_matching_key

Uses normalize_company_name internally and strips whitespace from the body name to produce a matching key for deduplication.

7. compare_company_names

Normalizes both names and compares them, returning a verdict, a confidence level, and reasons.

Design: the verdict and the reasons are both machine-generated from the same structured evidence

Rather than hand-writing the verdict/confidence logic and the explanatory text separately, this tool derives both from a single structured object, evidence, which is included as-is in the response:

Field

Meaning

scriptMismatch

Whether the body names differ so much in character type that comparison itself was judged meaningless

bodyMatch

How the body names relate: "exact", "partial", or "none"

commonTokens

The actual shared substring(s) found

labelMatch

Whether the corporate-form label (株式会社/合同会社/etc.) matches (null when not applicable)

positionMatch

Whether the prefix/suffix placement matches (null when not applicable)

distinguishing

The common-token + distinguishing-element pair behind a likely_different verdict (null otherwise)

The decision logic (evidence → verdict/confidence) and the explanation logic (evidence → reasons) are two separate functions that both read only from this same evidence object. Changing the decision rules automatically keeps the explanation in sync, so it's structurally impossible to end up with a confident verdict whose reasons/notes say "cannot be determined."

Script-mismatch guard (runs before any scoring)

If the two body names differ greatly in character type — one is Latin-only while the other contains Japanese (hiragana/katakana/kanji) — comparing them as strings is meaningless in principle. For example, "日本電気株式会社" (Nippon Electric Company) and "NEC" refer to the same company, yet their body-name strings share no characters at all ("NEC" is an abbreviation that cannot be detected by string comparison). Whenever this script mismatch is detected, the tool returns unknown (confidence: "low") immediately, before attempting any scoring.

Condition for returning likely_different

likely_different is returned only when all of the following hold:

  • The two body names share a common prefix or suffix ("common token") of at least 2 characters.

  • The remaining, non-shared part on each side (the "distinguishing element") is at least 2 characters long on both sides, and the two distinguishing elements differ.

Example: "東京電力" (Tokyo Electric Power) vs. "東北電力" (Tohoku Electric Power) — they share the suffix "電力" ("Electric Power") as a common token, with "東京" (Tokyo) and "東北" (Tohoku) as the distinguishing elements. Because both names follow the same naming pattern but diverge on a clear, region-identifying element, this tool treats them as likely different companies.

When this condition is not met (no shared part at all, or one name simply being a substring of the other), there is no positive evidence of being different companies, so the tool always returns unknown. The mere fact that two strings don't match or overlap is never, by itself, grounds for likely_different — string non-overlap is not evidence of being different entities. The reasons text distinguishes "no shared part at all" from "only a partial match" rather than using the same wording for both.

Confidence is capped at medium, and stays consistent with the verdict by construction

confidence has only two possible values: "medium" and "low". **"high" has been removed.** Since the 2006 enactment of the Companies Act abolished the similar-trade-name restriction, two unrelated companies can be registered under the same name as long as their head-office locations differ — so a match based on trade name alone can never justify strong confidence ("high"`) in principle.

The set of valid confidence values is constrained per verdict at the TypeScript type level: unknown can only ever carry confidence: "low", and both likely_same and likely_different can only ever carry confidence: "medium". It is structurally impossible for this tool to return unknown together with confidence: "medium".

This tool never "hedges by lowering confidence." When something is inherently indeterminate — such as the prefix/suffix placement mismatch below — the tool sets verdict itself to unknown rather than downgrading likely_same to a lower confidence. This matters for callers that branch purely on verdict (e.g. a batch job that auto-merges everything marked likely_same): such a caller would silently swallow the ambiguity if it were only reflected in confidence.

reasons always states concretely why the tool reached its conclusion — or why it couldn't (script mismatch, no shared token, partial overlap only, a mismatched corporate form or prefix/suffix placement, possibility of an abbreviation/English name, etc.), generated directly from evidence. Every response also includes a fixed note on the method's limitations:

This tool only performs text comparison based on notation normalization; it cannot judge whether an abbreviation, English name, or nickname refers to the same entity. A definitive identity check requires cross-referencing corporate numbers.

What this tool can and cannot determine

Case

Example

verdict

confidence

Body name, corporate form, and prefix/suffix placement all match

"株式会社サンプル" vs. "㈱サンプル"

likely_same

medium (same trade name could still belong to a different company — cross-reference the corporate number)

Body name and corporate form match, but prefix/suffix placement differs (prefix vs. suffix)

"株式会社サンプル" vs. "サンプル(株)"

unknown

low (prefix/suffix placement is part of the trade name itself — legally a different trade name that could belong to a different company)

Body name matches, but the corporate form itself differs (株式会社 vs. 合同会社)

"株式会社サンプル" vs. "合同会社サンプル"

unknown

low (an organizational conversion — e.g. a stock company converting to an LLC — keeps the same corporate number, so the two records could just be the same entity at different points in time)

Script mismatch (one Latin-only, the other contains Japanese)

"日本電気株式会社" vs. "NEC"

unknown

low (guard fires before scoring)

Shared common token (≥2 chars) with clearly different distinguishing elements (≥2 chars each)

"東京電力" vs. "東北電力"

likely_different

medium

One body name is a substring of the other (doesn't meet the distinguishing-element condition)

"株式会社サンプル" vs. "株式会社サンプル商事"

unknown

low

No shared token at all

"株式会社あいうえお" vs. "株式会社かきくけこ"

unknown

low

The only case where this tool returns likely_same (medium) is when the body name, corporate form, and prefix/suffix placement all match. Even when the body name appears to match, a differing prefix/suffix placement or a differing corporate form leaves a real possibility of a different entity that cannot be ruled out in principle, so the tool returns unknown. likely_different is returned only when the strict "shared pattern

  • clearly different identifier" condition above is met. Every other case is unknown. unknown does not mean "probably different" — it means "this method cannot determine it." When a definitive identity check is required, obtain each company's corporate number and cross-reference with validate_corporate_number or similar.

Primary sources

The number-validation logic was implemented only after retrieving and reading the following primary sources directly (last checked: 2026-07-29):

Items that could not be verified (disclosed honestly)

  • The specific numeric code table for the 2-digit "organization type" portion of the company registration number (e.g. which digits mean "stock company" vs. "LLC") could not be confirmed. Article 1-2 of the Commercial Registration Rules defines three textual categories ("stock companies"; "general/limited partnerships, LLCs, and foreign companies"; "trade-name users, etc."), but the reviewed statutory text does not spell out numeric codes for them, and secondary sources (blog posts, etc.) found online disagreed with each other. Because of this, parse_corporate_number returns only the raw 2-digit code with no interpretive label.

  • What the local-government sub-codes ("20" / "30") specifically distinguish (e.g. prefectures vs. municipalities) could not be confirmed.

  • The check-digit algorithm for the 13-digit invoice registration numbers issued to sole proprietors and unincorporated associations could not be confirmed as publicly documented. Numbers in this category are therefore validated for format only, with no mathematical check-digit verification.

  • The corporate-form and legacy-kanji dictionaries are not an exhaustive statutory definition; they are a practical, hand-curated set of commonly seen notations.

Setup

1. Prerequisites

node --version

2. Install dependencies

npm install

3. Build

npm run build

On success, build/index.js is created.

Using it from Claude Desktop

Add the following to your Claude Desktop config file (claude_desktop_config.json):

{
  "mcpServers": {
    "jp-corporate-id": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-jp-corporate-id/build/index.js"]
    }
  }
}

Config file locations:

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Restart Claude Desktop afterward, and tools such as validate_corporate_number become available.

Running tests

npm test

All tests should show ✔.

Project layout

mcp-jp-corporate-id/
├── src/
│   ├── sources.ts          … list of cited primary sources
│   ├── errors.ts            … shared validation-error class
│   ├── normalize.ts         … full/half-width, hyphen, etc. input normalization
│   ├── checkDigit.ts        … the check-digit formula
│   ├── corporateNumber.ts   … 12-digit base-number structure parsing
│   ├── corporateIdCalc.ts   … logic for tools 1-4
│   ├── companyNameData.ts   … corporate-form dictionary, legacy-kanji map
│   ├── companyName.ts       … logic for tools 5-7
│   └── index.ts             … MCP server entry point (registers the 7 tools)
├── tests/                   … automated tests (node:test)
├── package.json
├── tsconfig.json
├── LICENSE
├── README.md                … this file
└── README.ja.md             … Japanese version

Other servers by the same author:

  • mcp-jp-paid-leave — an MCP server for calculating statutory annual paid leave under Japan's Labor Standards Act

  • mcp-jp-calendar — an MCP server for Japanese business days, national holidays, gotobi settlement days, and fiscal quarters

License

MIT

Available Tools

7 tools
calculate_check_digit会社法人等番号から法人番号を算出A

会社法人等番号(12桁)から検査用数字(チェックデジット)を計算し、13桁の法人番号を算出します。全角数字・ハイフン・空白を含む入力も正規化して受け付けます。注意: 12桁の数字は会社法人等番号だけでなく個人番号(マイナンバー)とも桁数が同じです。個人番号は絶対に入力しないでください。本ツールは番号の種別を判定できません。

Inputs: companyCorporateNumber (required).

compare_company_names2つの法人名が同一法人を指すか判定A

2つの法人名を表記正規化した上で比較し、同一法人を指す可能性を判定理由・確信度とともに返します。応答には判定の根拠となった構造化データ(evidence: 本体名の一致状態・共通トークン・法人格ラベルの一致・前株後株の位置の一致・文字種の相違)を含み、reasonsはこの根拠から機械生成されます(手書きの固定文ではありません)。verdictは"likely_same"/"likely_different"/"unknown"の3値です。本体名の文字種が大きく異なる場合(一方がラテン文字のみ、他方が日本語を含む等)は、比較自体が原理的に無意味なためスコアリング前に必ずunknownを返します。"likely_different"は、共通の接頭辞・接尾辞(2文字以上)を持ちつつ、残りの識別要素が両方とも2文字以上あり明確に異なる場合(例: 「東京電力」と「東北電力」)に限定して返し、単に文字列が一致しない・重ならないというだけではlikely_differentにしません(文字列の不一致は別法人である証拠にはならないため)。前株・後株の位置が異なる場合(例: 「株式会社サンプル」と「サンプル株式会社」)は、前株・後株が商号の一部であり登記上まったく別の商号になりうるため、confidenceを下げるのではなくunknownを返します(verdictのみで分岐する呼び出し側が誤ってlikely_sameとして扱うことを避けるため)。法人格の種類自体が異なる場合(例: 株式会社と合同会社)も、組織変更では法人番号が変わらず時点の異なる同一法人のレコードである可能性があるためunknownを返します。2006年の会社法施行で類似商号規制が撤廃され、本店所在地が異なれば同一商号の別法人が登記できるため、商号の一致のみを根拠とする確信度は"medium"を上限とし"high"は使いません。confidenceはverdictと矛盾しないよう型で制約しており、unknownでconfidence:medium/highが返ることはありません。確実な同一性判定には法人番号での突合が必要です。

Inputs: nameA (required), nameB (required).

generate_matching_key名寄せ用の正規化キーを生成A

法人名から、法人格を除いた本体名を空白等を取り除いて正規化した、名寄せ用のキーを生成します。normalize_company_nameの結果を利用します。

Inputs: name (required).

normalize_company_name法人名の表記を正規化A

法人名の表記ゆれ(株式会社/(株)/(株)/㈱等の相互変換、前株・後株の判定、全角半角、主要な旧字体・異体字)を統一し、法人格を除いた本体名を分離して返します。対応する法人格・異体字の辞書は主要なものに限定しており、日本のすべての表記を網羅するものではありません。

Inputs: name (required).

parse_corporate_number法人番号の構造を解析A

法人番号(13桁)の検査用数字を検証した上で、区分(国の機関/地方公共団体/設立登記法人/設立登記のない法人・人格のない社団等)、設立登記法人の場合は登記所コード・組織区分(生の数字)・一連番号への内訳を返します。組織区分の数字と法人の種類(株式会社等)の対応表は、調査した一次資料の範囲では確認できなかったため、ラベル付けは行わず生の数字のみを返します。

Inputs: corporateNumber (required).

validate_corporate_number法人番号13桁の検査用数字を検証A

法人番号(13桁)の検査用数字(チェックデジット)が正しいかどうかを検証します。全角数字・ハイフン・空白を含む入力も正規化して受け付けます。形式(桁数・検査用数字)のみを検証するものであり、その法人番号が実在するかどうかは判定しません。実在確認は国税庁法人番号公表サイトで行ってください。

Inputs: corporateNumber (required).

validate_invoice_numberインボイス登録番号を検証A

適格請求書発行事業者の登録番号("T"+数字13桁)の形式を検証します。法人が保有する登録番号(T+法人番号)は検査用数字による数学的な検証まで行います。個人事業者・人格のない社団等が保有する登録番号は、マイナンバー・法人番号のいずれとも異なる国税庁独自の13桁の番号であり、その検査用数字の算出方法は公表が確認できていないため、形式検証のみを行います。実在確認・登録の有効性は保証しません。実在確認は国税庁適格請求書発行事業者公表サイトで行ってください。

Inputs: invoiceNumber (required).

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A4.4/5.0

    Scored across 7 tools

    Disambiguation5/5

    Each tool targets a distinct operation: validating a corporate number, calculating a check digit, validating an invoice number, parsing a corporate number's structure, normalizing a company name, generating a matching key, and comparing two names. Even where validation occurs in both parse_corporate_number and validate_corporate_number, the outputs and purposes are clearly differentiated. No two tools appear interchangeable.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern using snake_case, with verbs like validate, calculate, parse, normalize, generate, and compare. The naming style is uniform and predictable, with no mixed conventions.

    Tool Count5/5

    With 7 tools, the server is well-scoped for its purpose: three tools handle corporate number calculations/validation/parsing, one handles invoice numbers, and three handle company name normalization and comparison. Every tool serves a distinct need without redundancy.

    Completeness5/5

    The tool set covers the core operations for Japanese corporate identification: check-digit computation and validation, structural parsing, invoice number validation (with appropriate disclaimers), and company name normalization/key generation/comparison for matching. Existence checks are deliberately excluded and delegated to external public sites, which is a reasonable boundary. No critical missing operation for the server's intended scope.

    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
      C
      maintenance
      MCP server: validate Japanese qualified invoices (適格請求書) and registration numbers (T+13) from AI agents via jp-pint. Zero deps.
      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
    • A
      license
      A
      quality
      C
      maintenance
      MCP server for Japanese public business data, enabling AI agents to validate and look up corporate numbers, search bank/branch codes, and check national holidays. Runs locally with no telemetry; live corporate registry data requires a free NTA app ID.
      8
      MIT