jp-payroll-mcp

Японский расчёт заработной платы, социальное страхование и трудовое право — рассчитывается, а не ищется по справочникам: взносы для всех 47 префектур, налог у источника, решения и пересмотры стандартного вознаграждения, освобождения в отпуске, минимальная заработная плата — с указанием закона или министерского уведомления, на котором основан каждый ответ.

Проверено по опубликованным таблицам по ячейкам: 3 638 проверок при каждом изменении.

Два способа доступа

Как MCP-сервер — для вопросов через ИИ-ассистента. 17 инструментов, бесплатно, без ключа:

claude mcp add jp-payroll -- npx -y jp-payroll-mcp

Как HTTP API — для встраивания в программное обеспечение. 36 эндпоинтов, OpenAPI 3.0, пакетная обработка:

curl "https://japan-payroll-api.tsumugi.workers.dev/v1/payroll?prefecture=Tokyo&monthly_salary=350000&birth_date=1986-04-01"

MCP-сервер — это тонкая обёртка над API, поэтому оба варианта дают одинаковые ответы. Какой из них нужен, зависит от того, кто спрашивает: человек или программа.

• Исходный код MCP-сервера и его собственный README: mcp/ · 日本語

• Рабочий API: https://japan-payroll-api.tsumugi.workers.dev

• Спецификация OpenAPI: /openapi.json

Related MCP server: taiwan-payroll

Связанные инструменты

Японские MCP-серверы с нормативной информацией в основном извлекают — они выдают вам текст закона, а рассуждения оставляют вам. Этот же вычисляет и возвращает норму, на которую опирался. Они дополняют друг друга, а не конкурируют:

Если вы уже используете один из них, добавьте этот рядом. Ассистент, у которого есть оба, выбирает нужный инструмент для каждого вопроса.

Почему это существует

• Консолидированного API не существует. Разработчики собирают это по отдельности из 協会けんぽ, 厚生労働省 и каждого префектурального бюро труда.

• Правила каверзные. Взносы рассчитываются исходя из стандартного месячного вознаграждения (ступенчатой функции из 50 разрядов), а не из фактической зарплаты — за исключением страхования занятости, где используется фактическая зарплата. Пенсионные взносы ограничены 32-м разрядом. Взносы на долгосрочный уход применяются только к возрасту 40–64 лет. Доля работника округляется по правилу «половина вниз» (≤ 0,50 иены отбрасывается). Ошибка в любом из этих правил даёт числа, которые выглядят правдоподобно, но на самом деле неверны.

MCP-сервер

Исходный код в mcp/, со своим README · 日本語. Проверьте его командой npm run mcp:test — она запускает настоящий stdio-транспорт с настоящим MCP-клиентом, потому что инструмент со сломанным обработчиком по-прежнему отлично отображается в списке и даёт сбой только тогда, когда кто-то его вызывает.

MCP-сервер бесплатен и всегда таким останется. Это канал распространения, а не источник дохода: npm ничего не платит, а у MCP нет собственного биллинга. Это намеренное решение — проблема никогда не была в биллинге, который уже решает RapidAPI, а в обнаруживаемости; и трафик по японским нормативным данным, по измерениям, идёт именно в MCP.

Эндпоинты

prefecture принимает английское название (Tokyo, без учёта регистра), японское (東京 или 東京都) или код JIS (13).

Единственный вызов, который имеет значение

Расчёт зарплаты для одного сотрудника — это один запрос:

curl "https://japan-payroll-api.tsumugi.workers.dev/v1/payroll?prefecture=Tokyo&monthly_salary=350000&age=40&dependants=2"

gross                    350,000
social insurance          -55,750
                       ----------
after social insurance   294,250   <- the base withholding tax is charged on
withholding income tax    -4,480
                       ----------
net pay                  289,770

That middle line is the point. Income tax is charged on pay after social insurance, not on gross pay, and deriving it by hand is the mistake this endpoint exists to stop. The response also carries the grade that was resolved, every premium split into employee and employer shares, and which bracket produced the tax — so the arithmetic can be audited rather than trusted.

Resident tax (住民税) is assessed by the municipality and notified to the employer; no API can compute it. Pass resident_tax= and it will be subtracted from net pay.

Pass income_tax=false to get social insurance only.

Before you integrate

• GET /v1/enums lists every accepted value — business_type, column, calendar — and every error code, so they can be read at build time instead of discovered from a 400.

• Errors carry a stable code. invalid_request and missing_parameter mean fix the call; out_of_coverage means the input was valid but falls outside what is published, which needs a different branch. Do not match on the English prose — it will change.

• GET /v1/data-freshness tells you how current each dataset is.

Data

All figures are extracted programmatically from the official spreadsheets — not transcribed by hand. See scripts/ for the extractors.

Why not the statute

Income tax figures come from the National Tax Agency's published tables rather than from 所得税法 via the e-Gov law API, because the statutory version omits the 2.1% reconstruction surtax. At 105,000–107,000 yen the 乙 column is 3,700 yen in 別表第二 and 3,800 yen in practice; below 105,000 yen it is 3% rather than 3.063%. The statute is the wrong source for payroll.

Above 740,000 yen the table stops being a table: it becomes anchor points with a marginal rate. Those anchors are not collinear — rounding is baked into each — so the published anchor values are carried rather than recomputed. The 乙 column has only two anchors (740,000 and 1,710,000) where 甲 has nine, and measuring the 乙 excess from a 甲 anchor silently under-charges. That was a real bug here, caught by the cell-by-cell comparison.

Citations resolve to text

Naming a statute and leaving the reader to find it is half an answer. Every provision this API cites is bundled, so 健康保険法第43条 can be turned into its actual words in the same round trip:

curl 'https://japan-payroll-api.tsumugi.workers.dev/v1/statute?ref=健康保険法第43条'
curl '…/v1/standard-remuneration/revision?…&include=statute_text'

Citations are written many ways in practice and all of them resolve — 健保法43条, 厚年法81条の2, 徴収法11条, a missing 第, paragraph-level references, full-width digits. The e-Gov abbreviations are not the ones practitioners use (e-Gov calls it 厚生年金法; everyone writes 厚年法), so both are accepted.

Text comes from the e-Gov 法令API at build time rather than at request time: calling out to e-Gov on every request would mean this API goes down when theirs does.

scripts/extract-statutes.py holds the one list of provisions, and the test suite checks that every citation the code emits resolves — a citation added without a provision to back it fails the build rather than silently returning nothing.

Known gaps

• The year-end adjustment tables are not included. 令和8年分's 「給与所得控除後の給与等の金額の表」 was not yet published as of 2026-08; the Tax Agency releases it around September. 令和8年度税制改正 also raises the minimum employment income deduction to 740,000 yen with effect from 2026-12-01, so that table changes too.

• FY2026 minimum wage is not included. As of 2026-08, revisions were still being issued prefecture by prefecture and take effect from October 2026. The API serves FY2025, which is the rate currently in force. This must be refreshed once all 47 prefectures publish.

• Employment insurance history is FY2026 only. Earlier years were not verified against a primary source, so they are omitted rather than guessed.

• Resident tax is out of scope. It depends on the previous year's income and on the municipality, and it is levied by the municipality rather than computed by the employer, so /v1/payroll deducts whatever figure you pass and never derives one.

• The judgement endpoints decide whether a filing is due; they are not the filing. Several rules turn on facts an API cannot see — whether a seasonal swing is 「業務の性質上例年発生することが見込まれる」, whether an allowance is 実費弁償, whether the employee consented. Those are declared inputs, echoed back in the response, and the insurer can still reach a different conclusion under 保険者算定.

• Not every standard-remuneration route is covered. 資格取得時決定 returns how long the decision stays in force but does not compute the initial 報酬月額 (健保法42条1項 has four methods, three of which need figures about other employees). 二以上事業所 勤務 — where remuneration from several employers is summed and the premium split between them — is not implemented at all. Neither is the re-anchoring that happens when fixed pay changes twice inside the three-month window.

• A few practice points could not be sourced to a primary document and are listed as guidance.fixed_pay.unverified in the response rather than being asserted: whether 家族手当 counts as fixed pay, how paid leave is counted toward 支払基礎日数, and how 年俸制 is treated. Secondary sources agree on all three; the ministries do not appear to say so in writing.

Verification

test/verify.mjs runs 3,638 assertions against a live server. The core of it compares the API's computed premiums to the amounts printed in the official 協会けんぽ workbook for 250 prefecture × grade combinations — the published half-share figures, not a reimplementation of the formula. It also checks:

• grade boundary contiguity, and that a boundary yen value belongs to the upper grade

• pension clamping at grades 1 and 32

• long-term care switching on at 40 and off at 65

• employment insurance charged on actual salary while other premiums use the grade

• point-in-time minimum wage (including the day before an effective date)

• prefecture resolution across all four input forms

• all 47 prefectures returning a valid payroll response

• business-day counts against an independently computed reference

• the 2026-09-22 国民の休日 (a holiday only because it sits between two others)

• one-off imperial holidays: 大喪の礼, 即位礼正殿の儀, 結婚の儀

• the corporate-number check digit against the worked example in the NTA PDF, and that every other check digit is rejected for the same base

• every published cell of the withholding tax table — 231 brackets x 8 甲 columns plus the 乙 column, 2,079 figures, compared against the National Tax Agency's own workbook

• that a passing invoice check digit is not attributed to a corporation: sole proprietors satisfy the same rule, so the holder cannot be inferred from the number

• all eight single-grade 随時改定 cases 日本年金機構 publishes — four for health, four for pension — each landing on the standard remuneration the table names, on both the real grade and the extended scale the implementation uses

• that health and pension are judged independently: a raise above the pension ceiling moves six health grades and no pension grade at all

• the 15-day 定時決定 fallback firing for 短時間就労者 and not for anyone else, and not in 随時改定 at any time

• that every closed set of values appears in /v1/enums, so a new enum cannot ship without reaching the endpoint integrators generate their types from

npx wrangler dev --port 8799
node test/verify.mjs

# or against production
BASE=https://japan-payroll-api.tsumugi.workers.dev node test/verify.mjs

Develop / deploy

npm install
npx wrangler dev
npx wrangler deploy

Data is embedded in the bundle (~40 KB gzipped), so there is no database, no KV, and no cold start.

Responses carry Cache-Control: public, max-age=3600, stale-while-revalidate=86400. An hour rather than a day, because rates change on known dates and a correction should reach callers the same day; stale-while-revalidate keeps responses instant while the refresh happens behind it. Note that workers.dev responses are not cached at Cloudflare's own edge — every request invokes the Worker. A custom domain would enable edge caching if that becomes worth doing.

Measured from Japan against the deployed Worker: median 65 ms, max 83 ms round trip; gzip takes the 50-grade table from 6,841 to 1,041 bytes.

Maintenance

Statutory figures change on fixed dates, and an API that misses a revision keeps answering — with numbers that stopped being true. Two mechanisms guard against that.

The API reports its own staleness. GET /v1/data-freshness states what each dataset covers and when it is next due to change, and the main data responses carry a freshness marker. A caller can see a stale figure even if our monitoring failed.

A weekly job watches the sources.

npm run watch          # fingerprints each source, alerts Discord on change
npm run watch:dry      # same, without notifying

It checks two independent things, because either alone leaves a gap: the source file's hash and Last-Modified (catches a silent re-issue), and the calendar (catches the case where a ministry publishes the revision at a new URL and leaves the old one untouched).

An alert carries the exact commands for that dataset rather than pointing back here. The alert is read months later, usually by someone who has forgotten the layout of this repo.

Rehearse an extractor before you need it. The minimum wage extractor takes --check, which runs the full extraction and compares it to the data currently shipped instead of writing anything:

curl -L -A "Mozilla/5.0" -o mw.xlsx https://www.mhlw.go.jp/content/11200000/001571219.xlsx
python scripts/extract-minimum-wage.py --check

It should say the output matches. If it does not while the fiscal year is unchanged, the extractor and the shipped data have drifted apart — which is worth knowing in August rather than discovering on the day the new figures land, when the temptation is to ship whatever the script produces.

Register it to run weekly:

powershell -ExecutionPolicy Bypass -File scripts
egister_watch_task.ps1

Verifying the paid path

The test suite cannot check that RapidAPI's paid plans get full-size batches: doing so needs the proxy secret RapidAPI issues, and a secret that lives in a test is not a secret. It checks the half that matters for revenue — that a caller without the secret cannot claim a paid plan by setting a header.

Confirm the other half from the logs after any change to entitlement:

npx wrangler tail --format json

Call any endpoint from the RapidAPI playground and look for the request line. It should carry the subscription name:

{"channel":"rapidapi","path":"/","status":200,"plan":"BASIC"}

plan present means the proxy secret matches. plan: null on a rapidapi request means it does not — and every paying customer is being served the free-tier caps while being charged. That failure is silent from the outside, which is why it is worth a deliberate check rather than waiting for a complaint.

The dates that matter

After refreshing any dataset, update src/data/freshness.json and run npm run rapidapi:prepare so the live API is re-verified and the OpenAPI spec regenerated.

Publishing pipeline

Each API is a recipe under recipes/<slug>/recipe.py — endpoints are declared once there, and both the OpenAPI spec and the RapidAPI listing text are generated from it.

npm run rapidapi:prepare

That command, for every recipe:

1. validates the recipe,

2. hits every declared endpoint on the live API and requires a 200 with parseable JSON — and for endpoints with required parameters, requires a 400 when they are omitted. This is what catches drift between recipe.py and src/index.ts,

3. writes build/openapi/<slug>.openapi.json,

4. sends a Discord notification containing the listing URL, the spec path, and the exact values to paste.

Listing itself is manual. The Add-API form at https://rapidapi.com/provider/<id>/new is protected by reCAPTCHA v3, so the final submit is done by a person — three fields, choose "Specify using: OpenAPI", upload the generated spec. Roughly two minutes per API, which does not bottleneck a one-or-two-per-week cadence.

Set DISCORD_WEBHOOK_URL in .env (see .env.example) for the notification to actually arrive; without it the message only prints to the console.

Browser session

npm run rapidapi:login opens a real Chrome window for you to sign in by hand — the script never sees the password. The session persists in rapidapi_profile/ (gitignored). Re-run it when the session expires.

Operational safety

• state/pipeline.halt.json halts everything until a human removes it. set_halt() is called when a session dies; clear_halt() on successful re-login.

• MAX_PUBLISH_PER_DAY / MIN_SECONDS_BETWEEN_PUBLISH in pipeline/rapidapi/config.py keep the pace human.

Licence and attribution

Underlying data is Japanese government open data under 公共データ利用規約(第1.0版), which permits commercial use and redistribution with attribution. Every response carries an attribution block naming the source.

This service is not endorsed by any Japanese government agency. Verify against the official source before relying on it for statutory filings.