jp-invoice-check
An offline, read-only checker for Japanese qualified invoices (適格請求書): required items, per-rate tax rounding, registration-number format, and tax computation.
jp_invoice_check — validates the six required items (issuer + registration number, date, description with reduced-rate marks, totals per rate, tax per rate, buyer), recomputes tax per rate under floor/half-up/ceil and flags the per-line rounding mistake (
E_TAX_LINE_ROUNDING), returningok,errors,warnings,required_items,by_rate— messages in English and Japanese.jp_invoice_registration_number — normalizes full-width characters, spaces and hyphens, checks the
T+ 13-digit format and the corporate-number check digit.jp_invoice_tax — computes consumption tax rounded once per invoice per rate, tax-exclusive or tax-inclusive, using floor, half-up or ceil.
All tools are read-only, idempotent and offline (no network); they do not verify whether a number is currently registered with the NTA.
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-invoice-check Check this Japanese invoice for required items and per-rate tax rounding mistakes."
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 Invoice Check
An Agent Skill, CLI and MCP server that checks a Japanese qualified invoice (適格請求書): the six required items, reduced-rate marks, totals per rate, and the rule that consumption tax is rounded once per invoice per rate.
Japan's invoice system requires six items on every qualified invoice, and the tax must be rounded once per invoice for each rate, not line by line (NTA pamphlet: 「端数処理は一請求書当たり、税率ごとに1回ずつ」). A language model that writes an invoice tends to compute tax per line and add it up. On the example below that gives 597 yen instead of 599 for the 10% items and 285 instead of 286 for the 8% items.
This package computes instead of guessing:
checks the six items and returns each as true/false (
required_items)recomputes tax per rate for floor, half-up and ceil rounding (the method is the issuer's choice) and tells you which one the invoice used
names the per-line rounding mistake (
E_TAX_LINE_ROUNDING) separately from other wrong taxflags 8% items without a reduced-rate mark, and reduced marks on 10% items
normalizes the registration number (full-width, hyphens) and checks
T+ 13 digits and the corporate-number check digitreads ISO dates,
2026年10月28日,令和8年10月28日, and periodsnew in 0.2.0: compares the invoice with your company's own written rule (one rounding method, tax-exclusive or inclusive) and says how many yen a supplier's invoice differs and why
new in 0.2.0: the rule is fixed when a person starts the checker; the AI being checked cannot change it, and every result carries a fingerprint of the rules used
Every message comes in English and Japanese. Python standard library only. No network. MIT.
Your company rule (0.2.0)
Decide one rounding method for your company and write it down once:
{"name": "Example Co. invoice rules", "rounding": "floor", "price_basis": "exclusive"}Then every check also compares the invoice with that rule (policy_check):
role: "issue"(an invoice you send): not following your rule is an error (E_POLICY_ROUNDING,E_POLICY_PRICE_BASIS).role: "receive"(an invoice a supplier sent): their method may legally differ, so it is a warning (W_POLICY_ROUNDING) that names the method they used and the difference in yen. One check replaces the back-and-forth of finding why the numbers do not match.
Related MCP server: JP Invoice & Tax MCP
Keep the checker out of the AI's reach
A check is only worth something if the AI being checked cannot rewrite it. (Thanks to a reader's comment on Qiita for this point.)
Install it outside the agent's working folder and run it as a separate process, for example
pip install "git+https://github.com/japan-ai-tools/jp-invoice-check"into an environment the agent does not write to (PyPI may still have 0.1.0, which has no--policy; runpython -m jpinvoice --fingerprintand make sure it says 0.2.0 or later). Do not copy the source into the project the agent edits.Load the rule when you start it, not from the AI:
jp-invoice-check --policy /etc/company/invoice_policy.jsonor setJPINVOICE_POLICY. Make that file read-only and keep it outside the agent's folder. No tool argument can change it, and aroundingfield inside the invoice is ignored while a rule is loaded (W_INVOICE_ROUNDING_IGNORED).Deny edits to the install path and the policy file in your agent's permissions (in Claude Code, a
denyrule forEditandWriteon those paths).Check the fingerprint. Each result has
checker.code_sha256. For 0.2.0 it is:cd3e992f709f045f2047e8f4283e49ad3f825c2f752a5f984e29a66036eb32feIf it differs, the checking code was changed after installation.
python -m jpinvoice --fingerprintprints it.
Use as an Agent Skill
SKILL.md tells the agent to put the invoice into JSON and call the checker instead of computing tax itself. Prefer the MCP server (installed as above) and let the skill only call it.
To add the skill with the skills CLI: npx skills add japan-ai-tools/jp-invoice-check (it reads the SKILL.md at the repository root). / スキルだけ入れるなら npx skills add japan-ai-tools/jp-invoice-check。
CLI
python -m jpinvoice examples/ok.json # exit 0
python -m jpinvoice examples/line_rounding_mistake.json # exit 1, lists the errors
python -m jpinvoice invoice.json --policy examples/company_policy.json # an invoice you send
python -m jpinvoice supplier.json --policy examples/company_policy.json --role receive # one you received
python -m jpinvoice --fingerprint --policy examples/company_policy.json # which rules are in usefrom jpinvoice import check_invoice, expected_tax
expected_tax(5997, 10) # 599 (exclusive, floor)
expected_tax(1000, 10, "inclusive") # 90
check_invoice(invoice)["errors"] # [{level, code, field, message, message_ja}, ...]Many invoices from a CSV (for accounting staff / 経理の人向け)
Export the invoice lines from Excel or your accounting software as CSV (one row per line item, UTF-8 or Shift_JIS), then:
python -m jpinvoice.batch examples/invoices_sample.csv --html report.html [--policy company_policy.json] [--role receive]You get one HTML page: which invoices are fine, which have errors (for example E_TAX_LINE_ROUNDING), and why,
in Japanese. Headers can be Japanese (請求書番号・発行者・登録番号・取引日・買い手・税込税抜・品名・金額・税率・軽減・
10%対象額・10%税額・8%対象額・8%税額) or English. See examples/invoices_sample.csv. Nothing leaves your PC.
Excel や会計ソフトから請求書の明細を CSV(1行=1品目)で書き出し、上のコマンドで何十件でもまとめて検査できます。 結果は1枚の HTML(誤りの理由つき・日本語)。外部への通信はありません。
Without Python: one HTML file / Python なしで使う
Open offline/jp_invoice_check.html in a browser (double-click), choose the CSV or the Excel file (.xlsx, first sheet;
the old .xls format is not read), read the result. Since page version 0.3.0 the result can also be saved as a CSV
(one row per finding, UTF-8 with BOM) and printed on A4. The .xlsx reader is part of the page (no library, no network)
and is tested against the same data as CSV (tests/test_offline_xlsx.py). The same rules as the
Python checker; a test runs both on the same CSVs (sample, Shift_JIS and 500 generated invoices with typical mistakes)
and checks that they give the same verdicts and error codes (tests/test_offline_html.py, needs Node.js).
The page has a Content-Security-Policy of default-src 'none', so it cannot send your file anywhere.
offline/jp_invoice_check.html をダブルクリックしてブラウザで開き、CSV か Excel のファイル(.xlsx・1枚目のシート)を選びます。インストール不要。
古い形式の .xls は読めません。社内規則(端数処理・税抜/税込)と「自社が出す/取引先から受け取る」を選べます。
結果は HTML と CSV(1行=誤り1件)で保存でき、A4 で印刷できます。CSV のひな形も保存できます。ページは通信できない設定です。
MCP server (for AI agents)
Protocol: the stdio server speaks both MCP 2026-07-28 (stateless: server/discover, version and capabilities in each request's _meta, no initialize) and the older initialize flow (2025-06-18, 2025-03-26, 2024-11-05). Tests: tests/test_mcp_2026.py. 新しい MCP 2026-07-28(握手なし)と従来の initialize の両方で動きます。
{"mcpServers": {"jp-invoice-check": {"command": "jp-invoice-check", "args": ["--policy", "/etc/company/invoice_policy.json"]}}}Tool | Input | Returns |
|
|
|
| (none) |
|
|
|
|
|
|
|
All tools are read-only.
Over HTTP (remote MCP)
For agents that only connect to remote MCP servers (streamable HTTP). Standard library only, JSON responses, no sessions:
python -m jpinvoice.http_server --port 8765 [--policy company_policy.json] # http://127.0.0.1:8765/mcpIt binds to 127.0.0.1 unless you pass --host. Bodies over 1 MB are refused. GET / answers ok for health checks. If you expose it, put it behind your own authentication. (New in the GitHub source; the PyPI package gets it in the next release.)
How this differs from other free invoice checkers
We looked at the other free Japanese invoice MCP servers listed on Glama (checked 2026-11-03). Their descriptions cover registration-number checks, required items and tax calculation with one default rounding method. None of the descriptions we read says that it names the per-line rounding mistake. This package is built around that one rule:
it recomputes tax per rate with floor, half-up and ceil, and tells you which method the invoice used, instead of assuming one
it returns
E_TAX_LINE_ROUNDINGwhen the difference comes from rounding each line, separately from other wrong taxit compares a received invoice with your own written rounding rule (
E_POLICY_ROUNDING) and says how many yen differ
It does not look up whether a registration number is registered today (see Limits).
Error codes
E_REGNO_MISSING E_REGNO_FORMAT E_ISSUER_NAME_MISSING E_DATE_MISSING E_DATE_INVALID E_ITEMS_MISSING E_ITEM_DESCRIPTION_MISSING E_RATE_INVALID E_REDUCED_NOT_MARKED E_REDUCED_RATE_MISMATCH E_TOTAL_BY_RATE_MISSING E_TOTAL_MISMATCH E_TAX_MISSING E_TAX_LINE_ROUNDING E_TAX_MISMATCH E_BUYER_MISSING E_POLICY_ROUNDING E_POLICY_PRICE_BASIS; warnings W_REGNO_NORMALIZED W_REGNO_CHECK_DIGIT W_TOTAL_WITHOUT_ITEMS W_POLICY_ROUNDING W_POLICY_PRICE_BASIS W_INVOICE_ROUNDING_IGNORED.
Limits
Offline. It does not check whether a registration number is registered today; use the NTA publication site for that.
The check digit rule used is the corporate-number rule. For a sole proprietor's number a mismatch is reported only as a warning.
Simplified invoices (適格簡易請求書), return invoices and other special cases are not covered.
This is a checking tool, not tax advice.
Tests:
python -m unittest discover -s tests(26 tests)
日本語
適格請求書(インボイス)を検査する Agent Skill・コマンド・MCPサーバーです。
ほかの無料の検査道具との違い(Glama に載っている日本のインボイス用MCPの説明を 2026-11-03 に読んだ範囲): 登録番号・記載事項・税額の計算(端数処理は1つの方式が既定)を扱うものはありますが、「品目ごとに端数処理した誤り」を名前で返すと書いたものは見つかりませんでした。この道具は、切捨て・四捨五入・切上げのどれで計算されたかを当て、品目ごとの丸めの誤りを E_TAX_LINE_ROUNDING で、自社の端数処理の決まりとのずれを E_POLICY_ROUNDING で返します。登録番号が今も登録されているかの照会はしません。
記載事項6つ(発行者名と登録番号・取引年月日・取引内容と軽減税率の印・税率ごとの合計と税率・税率ごとの消費税額・買い手の名称)を1つずつ判定
消費税は「1つの請求書につき税率ごとに1回」端数処理。品目ごとに端数処理して足す誤り(AIがよくする)を
E_TAX_LINE_ROUNDINGで知らせます。切捨て・四捨五入・切上げのどれを使ったかも返します8%の品目に※などの印がない、10%なのに印がある、を検出
登録番号を整え(全角・ハイフン)、「T+13桁」と法人番号の検査用数字を確認
西暦・和暦(令和・平成)・期間の日付に対応
0.2.0 から: 自社の端数処理の規則(切捨て・四捨五入・切上げのどれか1つと、税抜か税込か)を1つのファイルに書いておくと、請求書と見比べます。自社が出す請求書(
issue)で規則と違えば誤り、取引先からの請求書(receive)なら「相手は四捨五入なので、自社の規則より+1円」のように、ずれの理由と金額を知らせます0.2.0 から: 規則は人が起動するときにだけ読み込みます(
--policyかJPINVOICE_POLICY)。検査されるAIの側からは変えられません。結果には検査に使った規則の指紋(sha256)がつくので、検査の中身が書き換えられていないかを確かめられます。検査の道具は、AIが書き換えられない場所に入れて使ってください(上の「Keep the checker out of the AI's reach」)
外部通信なし(登録が今も有効かは国税庁の公表サイトで確認してください)・Python標準ライブラリのみ・MIT。税務の助言ではありません。
Related tools from the same author
This checker does not ask whether a registration number is still registered. invoice-watch compares your supplier list with the NTA's published data and reports only the suppliers whose registration was cancelled, expired or renamed.
genba-shorui turns one site note into a daily report, an estimate and a qualified invoice in a single offline HTML page, with the same per-rate rounding check.
関連(同じ作者): 登録が今も有効かは 取引先インボイス見張り(invoice-watch) が取引先の一覧と国税庁の公表データを照らして、取消・失効・名称の変化だけを知らせます。現場のメモから日報・見積・請求書を作るなら 現場の書類(genba-shorui)。
Available Tools
3 toolsjp_invoice_checkCheck a Japanese qualified invoice (適格請求書)ARead-onlyIdempotent
Check a Japanese qualified invoice against the six required items of the National Tax Agency (issuer name + registration number, date, description with reduced-rate marks, total per rate, tax per rate, buyer name) and the rounding rule: consumption tax is rounded ONCE per invoice per rate, not per line. Catches the common mistake of summing per-line rounded tax. Input: issuer{name, registration_number}, date, buyer{name}, price_basis (exclusive|inclusive), items[{description, amount, rate 10|8, reduced}], totals[{rate, amount, tax}], optional rounding (floor|half_up|ceil). Returns ok, errors and warnings (code, field, message in English and Japanese), required_items, by_rate (expected tax for each rounding). Offline: it does not check whether the number is currently registered. 適格請求書の6項目と端数処理を検査。
Inputs: invoice (required).
jp_invoice_registration_numberCheck a Japanese invoice registration number (T + 13 digits)ARead-onlyIdempotent
Normalize (full-width, spaces, hyphens) and check the format 'T' + 13 digits, and the corporate-number check digit (correct for corporations). Returns normalized, valid_format, corporate_check_digit_ok, messages. Offline: registration status is not checked.
Inputs: number (required).
jp_invoice_taxConsumption tax for one rate on one invoiceARead-onlyIdempotent
Tax = round(total x rate) once for the whole invoice. price_basis exclusive: total x rate/100; inclusive: total x rate/(100+rate). rounding floor|half_up|ceil (default floor).
Inputs: rate (required), amount (required), rounding, price_basis.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 3 tools
Each tool has a distinct role: full invoice validation, registration-number format/check-digit validation, and tax calculation. The broad jp_invoice_check overlaps conceptually with the other two because it also considers registration number and rounding, but the descriptions make the intended boundaries mostly clear.
All names use snake_case and the jp_invoice_ prefix, which is predictable and readable. The suffixes are not a strict verb_noun pattern (check vs registration_number/tax), but there is no mixed convention.
Three tools are well-scoped for this narrow domain: full invoice check, registration-number handling, and tax calculation. Each tool earns its place without obvious bloat or thinness.
The set covers core offline invoice validation, registration-number format/check digit, and tax rounding. Minor gaps remain, such as no live registration-status lookup and no dedicated helper for aggregating item totals by rate, but these are stated limitations or workable manually.
Maintenance
Related MCP Connectors
Validate Japanese invoice registration numbers (T+13) and corporate numbers. No API key.
41Verify Japanese companies, invoice-issuer registrations and addresses against government open data.
Validate EU, UK, AU VAT numbers for AI agents. EU ViDA e-invoicing compliance.
Search Japanese corporations and verify invoice numbers using official National Tax Agency data.
Related MCP Servers
- AlicenseAqualityDmaintenanceEuropean business compliance suite for AI agents — 28 tools covering tax ID validation (PT, ES, FR, DE, IT, UK, NL), IBAN verification, EU VAT rates, invoice requirements, e-invoicing rules, payment terms, labor calendar helpers, VAT breakdown calculations and invoice schema validation for 18+ European countries.28MIT
- AlicenseNot gradedqualityCmaintenanceProvides Japanese tax and invoice utilities such as consumption tax calculation, withholding tax, invoice number validation, and tax rate summarization, enabling AI assistants to perform these operations locally without external APIs.MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to perform Japanese invoice and tax calculations, including consumption tax, withholding tax, invoice number validation, and invoice data generation, all locally without external APIs.MIT
- AlicenseAqualityBmaintenanceEnables AI agents to verify that every number, money amount, percentage, count, date and time in an AI-written Japanese summary or meeting minutes actually appears in the source text, normalizing kanji numerals, 万/億, full-width digits, Japanese era years, 午前/午後 times and 割/分 rates before comparison. Exposes a read-only check tool that reports each fact as supported, approximate, mismatched or unsupported, plus an extraction tool that lists the quantities in a text.21MIT