日本の給与・社会保険・労働法

Official30 toolsLive

by kishida-devil · JavaScript

Japan payroll & social insurance. 日本の給与計算・社会保険。47都道府県の料率、源泉所得税、割増賃金、有給、標準報酬月額の改定、最低賃金。根拠の条文つき。

io.github.kishida-devil/jp-payroll-mcp — Model Context Protocol (MCP) Server

This MCP server provides Japan payroll, social insurance, and labor-related calculations via tools, returning computed results rather than table lookups. It covers 47 prefectures’ insurance rates, withholding income tax, premium wages, paid leave, standard monthly remuneration revisions, minimum wage, and more.

🛠️ Key Features

47都道府県の保険料率
源泉所得税、割増賃金、有給休暇
標準報酬月額の決定と改定、休業中の保険料免除
最低賃金、営業日計算、令和8年分の年末調整
住民税の見込み額
根拠の条文または通知を付加

🚀 Use Cases

日本の給与計算・社会保険の根拠付き見積り
年末調整や住民税の見込み額計算の支援
管理・照合用の計算結果取得

⚡ Developer Benefits

MCP-based access using the remote MCP URL or npx installation
Calculation outputs with supporting legal text/notifications
Validated against published tables/tax tables with cell-by-cell cross-checks and 4,689 verifications per change

⚠️ Limitations

The server description does not specify toolCount or any guarantees beyond the included verification process.

Topics

apiclaudehrjapanjapaneselabor-lawmcpmodel-context-protocolpayrollsocial-insurance

Captured live from the server via tools/list.

calculate_payslip

Full monthly deduction breakdown for one employee: health insurance, long-term care, pension, child support, employment insurance, withholding income tax and net pay, with the employer share as well. Use this rather than computing it yourself. Premiums are charged on 標準報酬月額 — a 50-grade step function — and not on actual salary, while employment insurance IS charged on actual salary; the employee share rounds half DOWN; pension stops at grade 32; long-term care applies only from 40 to 64. Income tax is computed on pay after social insurance, which the tool derives internally, so do not pre-deduct it.

Parameters17

prefecture	string	required	Prefecture of the employer's 適用事業所 — English ("Tokyo"), Japanese ("東京" or "東京都"), or JIS code 1-47. Health insurance rates differ by prefecture; pension does not.
monthly_salary	number	required	Gross monthly pay in yen, before any deduction.
age	number	optional	Age in years. Either this or birth_date is required — long-term care is charged only from 40 to 64, so the premium cannot be settled without it. Prefer birth_date.
birth_date	string	optional	Date of birth, YYYY-MM-DD. Strongly preferred over `age`: 年齢計算ニ関スル法律 puts the attainment of an age on the day before the birthday, so someone born on the 1st of a month crosses a threshold in the previous month and their premium changes a month earlier than a naive calculation gives.
dependants	number	optional	源泉控除対象親族の数. Defaults to 0.
column	string	optional	甲 if the employee filed a 扶養控除等申告書 (the normal case), 乙 if not. Defaults to 甲.
business_type	string	optional	Employment insurance rate band. Defaults to general.
resident_tax	number	optional	Resident tax to deduct, in yen. It is levied by the municipality on the previous year's income and is never derived here — pass the figure from the 特別徴収税額通知書.
income_tax	boolean	optional	Set false to skip withholding tax. Defaults to true.
standard_remuneration	number	optional	The 標準報酬月額 fixed by 算定基礎届 or 月額変更届. Pass it whenever it is known. Without it the grade is re-derived from the pay you send, which is wrong in any month with overtime — a 300,000 yen earner who made 369,469 in a busy month is over-deducted by 8,445 yen. decide_regular_determination returns the right figure.
employment_type	string	optional	役員 are not employment-insurance insured (雇用保険法第4条). Pass "director" for a company officer, or the premium comes out too high. Defaults to employee.
commuting_allowance	number	optional	Commuting allowance in yen per month. Social insurance counts it as remuneration in full, income tax exempts it up to a ceiling — 150,000 a month by public transport. Do NOT fold it into monthly_salary: doing so taxes it, and leaving it out understates the premiums. The split comes back in earnings.items.
commuting_distance_km	number	optional	One-way distance for a car or bicycle commute. The exempt ceiling then comes from the distance table (国税庁 No.2585) rather than the 150,000 transit ceiling; under 2 km nothing is exempt.
commuting_parking	number	optional	Monthly parking the employee pays for a car or bicycle commute, in yen. Added to the distance band up to 5,000 a month. Needs commuting_distance_km — there is no band to add it to for someone who commutes only by train.
commuting_fare	number	optional	Reasonable fare or toll paid on top of a car or bicycle commute. With commuting_distance_km the ceiling is the distance band plus this, capped at 150,000.
workers_comp_type	string	optional	労災保険事業の種類の番号, e.g. "98" for wholesale/retail/restaurants/hotels. Workers compensation falls entirely on the employer and is left out unless you pass this, because rates run from 2.5/1000 to 88/1000 and there is no safe default. list_workers_compensation_rates has the table.
as_of	string	optional	The premium month: an ISO date in the month the person is insured for, NOT the pay date. Employers may deduct the previous month's premium from this month's pay (Health Insurance Act art. 167), so with next-month deduction pass a date in the month before the pay date. Drives the age milestones and picks the rate table; a date outside the published period returns 422 rather than the current table.

Raw schema

{
  "type": "object",
  "properties": {
    "prefecture": {
      "type": "string",
      "description": "Prefecture of the employer's 適用事業所 — English (\"Tokyo\"), Japanese (\"東京\" or \"東京都\"), or JIS code 1-47. Health insurance rates differ by prefecture; pension does not."
    },
    "monthly_salary": {
      "type": "number",
      "description": "Gross monthly pay in yen, before any deduction."
    },
    "age": {
      "description": "Age in years. Either this or birth_date is required — long-term care is charged only from 40 to 64, so the premium cannot be settled without it. Prefer birth_date.",
      "type": "number"
    },
    "birth_date": {
      "description": "Date of birth, YYYY-MM-DD. Strongly preferred over `age`: 年齢計算ニ関スル法律 puts the attainment of an age on the day *before* the birthday, so someone born on the 1st of a month crosses a threshold in the previous month and their premium changes a month earlier than a naive calculation gives.",
      "type": "string"
    },
    "dependants": {
      "description": "源泉控除対象親族の数. Defaults to 0.",
      "type": "number"
    },
    "column": {
      "description": "甲 if the employee filed a 扶養控除等申告書 (the normal case), 乙 if not. Defaults to 甲.",
      "type": "string",
      "enum": [
        "kou",
        "otsu"
      ]
    },
    "business_type": {
      "description": "Employment insurance rate band. Defaults to general.",
      "type": "string",
      "enum": [
        "general",
        "agriculture_forestry_fishery_sake",
        "construction"
      ]
    },
    "resident_tax": {
      "description": "Resident tax to deduct, in yen. It is levied by the municipality on the previous year's income and is never derived here — pass the figure from the 特別徴収税額通知書.",
      "type": "number"
    },
    "income_tax": {
      "description": "Set false to skip withholding tax. Defaults to true.",
      "type": "boolean"
    },
    "standard_remuneration": {
      "description": "The 標準報酬月額 fixed by 算定基礎届 or 月額変更届. Pass it whenever it is known. Without it the grade is re-derived from the pay you send, which is wrong in any month with overtime — a 300,000 yen earner who made 369,469 in a busy month is over-deducted by 8,445 yen. decide_regular_determination returns the right figure.",
      "type": "number"
    },
    "employment_type": {
      "description": "役員 are not employment-insurance insured (雇用保険法第4条). Pass \"director\" for a company officer, or the premium comes out too high. Defaults to employee.",
      "type": "string",
      "enum": [
        "employee",
        "director",
        "director_employee"
      ]
    },
    "commuting_allowance": {
      "description": "Commuting allowance in yen per month. Social insurance counts it as remuneration in full, income tax exempts it up to a ceiling — 150,000 a month by public transport. Do NOT fold it into monthly_salary: doing so taxes it, and leaving it out understates the premiums. The split comes back in earnings.items.",
      "type": "number"
    },
    "commuting_distance_km": {
      "description": "One-way distance for a car or bicycle commute. The exempt ceiling then comes from the distance table (国税庁 No.2585) rather than the 150,000 transit ceiling; under 2 km nothing is exempt.",
      "type": "number"
    },
    "commuting_parking": {
      "description": "Monthly parking the employee pays for a car or bicycle commute, in yen. Added to the distance band up to 5,000 a month. Needs commuting_distance_km — there is no band to add it to for someone who commutes only by train.",
      "type": "number"
    },
    "commuting_fare": {
      "description": "Reasonable fare or toll paid on top of a car or bicycle commute. With commuting_distance_km the ceiling is the distance band plus this, capped at 150,000.",
      "type": "number"
    },
    "workers_comp_type": {
      "description": "労災保険 事業の種類の番号, e.g. \"98\" for wholesale/retail/restaurants/hotels. Workers compensation falls entirely on the employer and is left out unless you pass this, because rates run from 2.5/1000 to 88/1000 and there is no safe default. list_workers_compensation_rates has the table.",
      "type": "string"
    },
    "as_of": {
      "description": "The premium month: an ISO date in the month the person is insured for, NOT the pay date. Employers may deduct the previous month's premium from this month's pay (Health Insurance Act art. 167), so with next-month deduction pass a date in the month before the pay date. Drives the age milestones and picks the rate table; a date outside the published period returns 422 rather than the current table.",
      "type": "string"
    }
  },
  "required": [
    "prefecture",
    "monthly_salary"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

list_workers_compensation_rates

Workers compensation (労災保険) rates by business type, and the employer premium on a given 賃金総額. The whole premium falls on the employer — nothing is deducted from the employee, unlike every other statutory premium. Rates run from 2.5/1000 to 88/1000 depending on the industry, a 35-fold spread, so this cannot be estimated. Pass the 事業の種類の番号 from the 労働保険関係成立届; omit it to get the whole table.

Parameters3

business_type	string	optional	事業の種類の番号 (02-99), e.g. "35" for 建築事業 or "98" for wholesale and retail.
wage_total	number	optional	賃金総額 for the period, in yen — the same wage base employment insurance uses, so a commuting allowance counts and a reimbursement does not.
as_of	string	optional	ISO date the wages relate to.

Raw schema

{
  "type": "object",
  "properties": {
    "business_type": {
      "description": "事業の種類の番号 (02-99), e.g. \"35\" for 建築事業 or \"98\" for wholesale and retail.",
      "type": "string"
    },
    "wage_total": {
      "description": "賃金総額 for the period, in yen — the same wage base employment insurance uses, so a commuting allowance counts and a reimbursement does not.",
      "type": "number"
    },
    "as_of": {
      "description": "ISO date the wages relate to.",
      "type": "string"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

calculate_bonus

Premiums and income tax on a 賞与. Both work differently from monthly pay and are routinely got wrong. Premiums are charged on 標準賞与額 (the bonus truncated to the thousand yen) under two caps that behave differently: health, long-term care and child support cap at 5,730,000 yen CUMULATIVELY across the fiscal year from 1 April, while pension caps at 1,500,000 yen PER PAYMENT. The annual cap cannot be applied without fiscal_year_to_date, so pass it whenever an earlier bonus was paid in the same fiscal year. Withholding tax on a bonus is derived from the PREVIOUS month's pay, not from the bonus itself. Set include_tax to also compute it.

Parameters11

prefecture	string	required	Prefecture of the employer's 適用事業所 — English ("Tokyo"), Japanese ("東京" or "東京都"), or JIS code 1-47. Health insurance rates differ by prefecture; pension does not.
bonus	number	required	Gross bonus in yen.
fiscal_year_to_date	number	optional	標準賞与額 already paid since 1 April this fiscal year. Needed for the annual health cap.
age	number	optional	Age in years. Either this or birth_date is required. Prefer birth_date.
birth_date	string	optional	Date of birth, YYYY-MM-DD. Strongly preferred over `age`: 年齢計算ニ関スル法律 puts the attainment of an age on the day before the birthday, so someone born on the 1st of a month crosses a threshold in the previous month and their premium changes a month earlier than a naive calculation gives.
as_of	string	optional	YYYY-MM-DD. Which rate table to use. Rates change every March, so a bonus paid in a previous year needs the table that was in force then; the call is refused rather than answered with today's rates.
column	string	optional	Withholding column for the tax half: 甲 when a 扶養控除等申告書 was filed (the normal case), 乙 when it was not. 乙 has its own rate table. Defaults to 甲.
include_tax	boolean	optional	Also compute withholding tax. Requires previous_month_pay.
previous_month_pay	number	optional	Gross pay in the month before the bonus. The tax rate is derived from this.
previous_month_insurance	number	optional	Social insurance deducted from that previous month's pay.
dependants	number	optional

Raw schema

{
  "type": "object",
  "properties": {
    "prefecture": {
      "type": "string",
      "description": "Prefecture of the employer's 適用事業所 — English (\"Tokyo\"), Japanese (\"東京\" or \"東京都\"), or JIS code 1-47. Health insurance rates differ by prefecture; pension does not."
    },
    "bonus": {
      "type": "number",
      "description": "Gross bonus in yen."
    },
    "fiscal_year_to_date": {
      "description": "標準賞与額 already paid since 1 April this fiscal year. Needed for the annual health cap.",
      "type": "number"
    },
    "age": {
      "description": "Age in years. Either this or birth_date is required. Prefer birth_date.",
      "type": "number"
    },
    "birth_date": {
      "description": "Date of birth, YYYY-MM-DD. Strongly preferred over `age`: 年齢計算ニ関スル法律 puts the attainment of an age on the day *before* the birthday, so someone born on the 1st of a month crosses a threshold in the previous month and their premium changes a month earlier than a naive calculation gives.",
      "type": "string"
    },
    "as_of": {
      "description": "YYYY-MM-DD. Which rate table to use. Rates change every March, so a bonus paid in a previous year needs the table that was in force then; the call is refused rather than answered with today's rates.",
      "type": "string"
    },
    "column": {
      "description": "Withholding column for the tax half: 甲 when a 扶養控除等申告書 was filed (the normal case), 乙 when it was not. 乙 has its own rate table. Defaults to 甲.",
      "type": "string",
      "enum": [
        "kou",
        "otsu"
      ]
    },
    "include_tax": {
      "description": "Also compute withholding tax. Requires previous_month_pay.",
      "type": "boolean"
    },
    "previous_month_pay": {
      "description": "Gross pay in the month before the bonus. The tax rate is derived from this.",
      "type": "number"
    },
    "previous_month_insurance": {
      "description": "Social insurance deducted from that previous month's pay.",
      "type": "number"
    },
    "dependants": {
      "type": "number"
    }
  },
  "required": [
    "prefecture",
    "bonus"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

calculate_withholding_tax

Income tax to withhold from a payment, from the National Tax Agency tables. The taxable amount is pay AFTER social insurance has been deducted, not gross. Pick the table with `period`: "monthly" for 月額表, "daily" for 日額表. The daily table has a third column, 丙, which applies to work engaged by the day and takes no dependant adjustment at all. Use `method: "computer"` for the 電算機計算の特例 formula, which payroll software may use instead of the table and can differ by a few yen.

Parameters6

taxable_amount	number	required	Pay after social insurance, in yen.
period	string	optional	Defaults to monthly.
column	string	optional	甲/乙, plus 丙 for the daily table only. Defaults to 甲.
spouse	boolean	optional	Only for method "computer": whether a 源泉控除対象配偶者 is claimed. The formula method deducts 31,667 yen a month for one, which the monthly table folds into its columns instead. Ignored by the table methods.
dependants	number	optional
method	string	optional	"computer" selects the statutory formula method. Monthly only. Defaults to table.

Raw schema

{
  "type": "object",
  "properties": {
    "taxable_amount": {
      "type": "number",
      "description": "Pay after social insurance, in yen."
    },
    "period": {
      "description": "Defaults to monthly.",
      "type": "string",
      "enum": [
        "monthly",
        "daily"
      ]
    },
    "column": {
      "description": "甲/乙, plus 丙 for the daily table only. Defaults to 甲.",
      "type": "string",
      "enum": [
        "kou",
        "otsu",
        "hei"
      ]
    },
    "spouse": {
      "description": "Only for method \"computer\": whether a 源泉控除対象配偶者 is claimed. The formula method deducts 31,667 yen a month for one, which the monthly table folds into its columns instead. Ignored by the table methods.",
      "type": "boolean"
    },
    "dependants": {
      "type": "number"
    },
    "method": {
      "description": "\"computer\" selects the statutory formula method. Monthly only. Defaults to table.",
      "type": "string",
      "enum": [
        "table",
        "computer"
      ]
    }
  },
  "required": [
    "taxable_amount"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

judge_monthly_revision

Decides whether a pay change forces the standard remuneration to be revised, and answers SEPARATELY for health insurance and pension — the tables differ, so a change routinely moves one and not the other. Above roughly 665,000 yen the pension table is exhausted, so a large raise for a well-paid employee moves several health grades and no pension grade. Do not try to reason this out unaided. Neither the "two grades or more" test nor the requirement that FIXED pay changed appears anywhere in 健康保険法 or its regulations — both come from 昭和36年保発第4号, a ministerial notice, along with four exceptions near the top and bottom of each table where a single grade is enough. Overtime alone never triggers a revision, and a rise in fixed pay whose three-month average comes out LOWER is excluded even at a wide grade gap. When the answer is no, the response says which requirement failed rather than just false. If the three-month average is distorted by a seasonal peak, see judge_annual_average.

Parameters4

current_remuneration	number	required	The 報酬月額 the CURRENT grade was based on — the actual pay figure, not the 標準報酬月額. The upper and lower exceptions turn on actual pay, so substituting the grade's standard value gives a wrong answer at the extremes.
months	string	required	Three months as "remuneration:payment_basis_days", comma separated — e.g. "350000:31,352000:30,349000:31". 支払基礎日数 is calendar days for monthly-paid staff, or days actually worked for daily-paid staff.
fixed_pay_change	string	required	Whether FIXED pay changed: base pay, rate changes, a new or altered fixed allowance, a change of pay basis. Overtime and other variable pay are not fixed pay — use "none" and the tool will explain why no revision follows.
worker_type	string	optional	general = 一般の被保険者 (17-day threshold). part_time_short_hours = 短時間就労者, works shorter hours but meets the three-quarters test (17 days, with a 15-day fallback that exists ONLY in 定時決定). short_time_insured = 短時間労働者 at a 特定適用事業所 (11 days). Defaults to general.

Raw schema

{
  "type": "object",
  "properties": {
    "current_remuneration": {
      "type": "number",
      "description": "The 報酬月額 the CURRENT grade was based on — the actual pay figure, not the 標準報酬月額. The upper and lower exceptions turn on actual pay, so substituting the grade's standard value gives a wrong answer at the extremes."
    },
    "months": {
      "type": "string",
      "description": "Three months as \"remuneration:payment_basis_days\", comma separated — e.g. \"350000:31,352000:30,349000:31\". 支払基礎日数 is calendar days for monthly-paid staff, or days actually worked for daily-paid staff."
    },
    "fixed_pay_change": {
      "type": "string",
      "enum": [
        "increase",
        "decrease",
        "none"
      ],
      "description": "Whether FIXED pay changed: base pay, rate changes, a new or altered fixed allowance, a change of pay basis. Overtime and other variable pay are not fixed pay — use \"none\" and the tool will explain why no revision follows."
    },
    "worker_type": {
      "description": "general = 一般の被保険者 (17-day threshold). part_time_short_hours = 短時間就労者, works shorter hours but meets the three-quarters test (17 days, with a 15-day fallback that exists ONLY in 定時決定). short_time_insured = 短時間労働者 at a 特定適用事業所 (11 days). Defaults to general.",
      "type": "string",
      "enum": [
        "general",
        "part_time_short_hours",
        "short_time_insured"
      ]
    }
  },
  "required": [
    "current_remuneration",
    "months",
    "fixed_pay_change"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

decide_regular_remuneration

The yearly redetermination of standard remuneration, effective each September through the following August. Months below the payment-basis-day threshold drop OUT of the average entirely — they are not counted as zero, which is the usual mistake. If no month qualifies, the previous grade carries over by 保険者算定, except for 短時間就労者, who have an intermediate step at 15 days that exists nowhere else in the scheme and not in 随時改定. Pass acquired_month to also learn how long a 資格取得時決定 stays in force.

Parameters8

months	string	required	April, May and June as "remuneration:payment_basis_days" — e.g. "350000:30,352000:31,349000:30".
worker_type	string	optional	general = 一般の被保険者 (17-day threshold). part_time_short_hours = 短時間就労者, works shorter hours but meets the three-quarters test (17 days, with a 15-day fallback that exists ONLY in 定時決定). short_time_insured = 短時間労働者 at a 特定適用事業所 (11 days). Defaults to general.
year	number	optional	The determination year; its 1 July is the reference date. Defaults to the current year.
acquired_on	string	optional	Date cover began, YYYY-MM-DD. Someone insured between 1 June and 1 July is outside the annual determination (健康保険法第41条).
left_on	string	optional	Last day worked, YYYY-MM-DD. Gone before 1 July means not employed on the reference date.
revision_month	number	optional	Month a 随時改定 takes effect. July, August or September displaces the annual determination; any other month does not.
previous_remuneration	number	optional	The prior 報酬月額, so the response can name the grade that carries over if no month qualifies.
acquired_month	number	optional	Month of enrolment, 1-12. Returns how long the 資格取得時決定 applies.

Raw schema

{
  "type": "object",
  "properties": {
    "months": {
      "type": "string",
      "description": "April, May and June as \"remuneration:payment_basis_days\" — e.g. \"350000:30,352000:31,349000:30\"."
    },
    "worker_type": {
      "description": "general = 一般の被保険者 (17-day threshold). part_time_short_hours = 短時間就労者, works shorter hours but meets the three-quarters test (17 days, with a 15-day fallback that exists ONLY in 定時決定). short_time_insured = 短時間労働者 at a 特定適用事業所 (11 days). Defaults to general.",
      "type": "string",
      "enum": [
        "general",
        "part_time_short_hours",
        "short_time_insured"
      ]
    },
    "year": {
      "description": "The determination year; its 1 July is the reference date. Defaults to the current year.",
      "type": "number"
    },
    "acquired_on": {
      "description": "Date cover began, YYYY-MM-DD. Someone insured between 1 June and 1 July is outside the annual determination (健康保険法第41条).",
      "type": "string"
    },
    "left_on": {
      "description": "Last day worked, YYYY-MM-DD. Gone before 1 July means not employed on the reference date.",
      "type": "string"
    },
    "revision_month": {
      "description": "Month a 随時改定 takes effect. July, August or September displaces the annual determination; any other month does not.",
      "type": "number"
    },
    "previous_remuneration": {
      "description": "The prior 報酬月額, so the response can name the grade that carries over if no month qualifies.",
      "type": "number"
    },
    "acquired_month": {
      "description": "Month of enrolment, 1-12. Returns how long the 資格取得時決定 applies.",
      "type": "number"
    }
  },
  "required": [
    "months"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

judge_leave_end_revision

A separate route with a lower bar than 随時改定, and the one people forget. ONE grade of movement is enough, and fixed pay need not have changed at all — which matters because returning to shorter hours usually cuts pay without changing any rate, so 随時改定 would not fire and the employee would keep overpaying on their pre-leave grade. Only one of the three months has to reach the day threshold, and months that miss it are excluded from the average. The employee must apply; an employer cannot file it alone. It is unavailable if another leave begins the day after this one ends.

Parameters5

kind	string	required	産前産後休業終了時改定 or 育児休業等終了時改定.
current_remuneration	number	required	報酬月額 before the leave.
months	string	required	Three months starting with the one containing the day AFTER the leave ended.
worker_type	string	optional	general = 一般の被保険者 (17-day threshold). part_time_short_hours = 短時間就労者, works shorter hours but meets the three-quarters test (17 days, with a 15-day fallback that exists ONLY in 定時決定). short_time_insured = 短時間労働者 at a 特定適用事業所 (11 days). Defaults to general.
next_leave_starts_immediately	boolean	optional	True if another leave began the day after this one ended, which bars the application.

Raw schema

{
  "type": "object",
  "properties": {
    "kind": {
      "type": "string",
      "enum": [
        "maternity",
        "childcare"
      ],
      "description": "産前産後休業終了時改定 or 育児休業等終了時改定."
    },
    "current_remuneration": {
      "type": "number",
      "description": "報酬月額 before the leave."
    },
    "months": {
      "type": "string",
      "description": "Three months starting with the one containing the day AFTER the leave ended."
    },
    "worker_type": {
      "description": "general = 一般の被保険者 (17-day threshold). part_time_short_hours = 短時間就労者, works shorter hours but meets the three-quarters test (17 days, with a 15-day fallback that exists ONLY in 定時決定). short_time_insured = 短時間労働者 at a 特定適用事業所 (11 days). Defaults to general.",
      "type": "string",
      "enum": [
        "general",
        "part_time_short_hours",
        "short_time_insured"
      ]
    },
    "next_leave_starts_immediately": {
      "description": "True if another leave began the day after this one ended, which bars the application.",
      "type": "boolean"
    }
  },
  "required": [
    "kind",
    "current_remuneration",
    "months"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

calculate_payroll_batch

Runs calculate_payslip for many employees in one call and returns the run totals: gross, employee deductions, net, and employer cost. Reach for this the moment more than two or three people are in play. A monthly payroll is not a sequence of unrelated questions — the employer share, the totals and the run id only mean anything across the whole run. Asking one employee at a time gives no total and no way to tell a retry from a second run. Put anything shared in defaults (prefecture, business_type, column) and let each row carry only what differs, which is usually pay and age. A row that cannot be computed comes back in errors with its index and id while the rest of the run completes — do not discard a whole payroll over one bad row. The reply carries a run_id derived from the route and the exact input, so sending the same payroll twice gives the same id. Nothing is stored, so a retry cannot double-count.

Parameters3

employees	array	required	One entry per employee. Up to 500 on a paid plan, 10 on the free tier.
defaults	object	optional	Applied to any row that leaves the field out.
compact	boolean	optional	Drop the per-employee breakdown and keep the payout figures — about a tenth the size on a large run. Use it when the question is "what do we pay", not "why".

Raw schema

{
  "type": "object",
  "properties": {
    "employees": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "description": "Echoed back on the result and on any error.",
            "type": "string"
          },
          "monthly_salary": {
            "type": "number",
            "description": "Gross monthly pay in yen, before any deduction."
          },
          "prefecture": {
            "description": "Overrides defaults.prefecture for this row.",
            "type": "string"
          },
          "age": {
            "type": "number"
          },
          "birth_date": {
            "description": "YYYY-MM-DD. Preferred over age.",
            "type": "string"
          },
          "business_type": {
            "type": "string"
          },
          "column": {
            "type": "string",
            "enum": [
              "kou",
              "otsu"
            ]
          },
          "dependants": {
            "type": "number"
          },
          "income_tax": {
            "type": "boolean"
          },
          "resident_tax": {
            "type": "number"
          },
          "workers_comp_type": {
            "type": "string"
          },
          "employment_type": {
            "type": "string",
            "enum": [
              "employee",
              "director",
              "director_employee"
            ]
          },
          "standard_remuneration": {
            "description": "The 標準報酬月額 already fixed for this person. Pass it whenever it is known — without it the grade is re-derived from the pay you send, which is wrong in any month with overtime.",
            "type": "number"
          }
        },
        "required": [
          "monthly_salary"
        ]
      },
      "description": "One entry per employee. Up to 500 on a paid plan, 10 on the free tier."
    },
    "defaults": {
      "description": "Applied to any row that leaves the field out.",
      "type": "object",
      "properties": {
        "prefecture": {
          "type": "string"
        },
        "age": {
          "type": "number"
        },
        "business_type": {
          "type": "string"
        },
        "column": {
          "type": "string",
          "enum": [
            "kou",
            "otsu"
          ]
        },
        "dependants": {
          "type": "number"
        },
        "income_tax": {
          "type": "boolean"
        },
        "resident_tax": {
          "type": "number"
        },
        "workers_comp_type": {
          "type": "string"
        }
      }
    },
    "compact": {
      "description": "Drop the per-employee breakdown and keep the payout figures — about a tenth the size on a large run. Use it when the question is \"what do we pay\", not \"why\".",
      "type": "boolean"
    }
  },
  "required": [
    "employees"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

decide_regular_remuneration_batch

Runs the annual 定時決定 for a whole payroll in one call, and reports which employees moved grade. 健康保険法第41条 puts every insured employee on the same schedule — the average of April, May and June pay, over the months with at least seventeen payment-basis days, applied from September to the following August. So June is the one month of the year when an office decides its entire payroll at once, and asking about one employee at a time is the wrong shape for the task. Reach for this the moment more than a couple of employees are in play. Each row returns the same judgement as decide_regular_remuneration, plus whether that person changed grade, which is what decides how much filing there is. Pass previous_remuneration to get that comparison; without it the answer is null rather than false, because "no grade to compare" and "did not move" are different facts. Pass acquired_on, left_on or revision_month and each row also says whether that employee is filed at all. 健康保険法第41条 leaves out anyone insured between 1 June and 1 July, anyone gone before the 1 July reference date, and anyone revised from July to September. The run totals to_file and not_required, which is the number of forms rather than the number of employees. A row that cannot be decided is returned in errors with its index and id, and the rest of the run still completes — do not discard a whole run over one bad row.

Parameters2

employees	array	required	One entry per employee.
defaults	object	optional	Applied to any row that omits the field.

Raw schema

{
  "type": "object",
  "properties": {
    "employees": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "description": "Echoed back on the result and on any error.",
            "type": "string"
          },
          "months": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "remuneration": {
                  "type": "number",
                  "description": "Total pay for that month, in yen."
                },
                "payment_basis_days": {
                  "type": "number",
                  "description": "支払基礎日数 for that month."
                }
              },
              "required": [
                "remuneration",
                "payment_basis_days"
              ]
            },
            "description": "Exactly three entries: April, May and June, in that order."
          },
          "worker_type": {
            "type": "string",
            "enum": [
              "general",
              "part_time_short_hours",
              "short_time_insured"
            ]
          },
          "previous_remuneration": {
            "description": "The 標準報酬月額 in force before this determination, so the result can say whether it moved.",
            "type": "number"
          },
          "acquired_on": {
            "description": "Date cover began, YYYY-MM-DD. Between 1 June and 1 July is outside the determination.",
            "type": "string"
          },
          "left_on": {
            "description": "Last day worked, YYYY-MM-DD. Gone before 1 July means not filed.",
            "type": "string"
          },
          "revision_month": {
            "description": "Month a 随時改定 takes effect. July to September displaces the determination.",
            "type": "number"
          }
        },
        "required": [
          "months"
        ]
      },
      "description": "One entry per employee."
    },
    "defaults": {
      "description": "Applied to any row that omits the field.",
      "type": "object",
      "properties": {
        "year": {
          "description": "The determination year. Defaults to the current year.",
          "type": "number"
        },
        "worker_type": {
          "type": "string",
          "enum": [
            "general",
            "part_time_short_hours",
            "short_time_insured"
          ]
        },
        "previous_remuneration": {
          "type": "number"
        }
      }
    }
  },
  "required": [
    "employees"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

judge_annual_average

For work whose April-June happens to be its busiest or quietest quarter, where the ordinary calculation would fix a grade that is wrong for eleven months of the year. Available for 定時決定 (since April 2011) and 随時改定 (since October 2018). The 随時改定 figure is NOT a plain twelve-month average: it is the three-month average of FIXED pay plus the twelve-month average of NON-FIXED pay, so the two are supplied separately, and three distinct grade tests must all pass. Both routes need the employee's consent and require that the swing recurs every year for reasons inherent to the work — a one-off busy period does not qualify. Neither is something this tool can verify, so both are declared inputs and are echoed back in the response.

Parameters7

type	string	required	regular = 定時決定の年間平均, revision = 随時改定の年間平均.
months	array	required	Exactly 12 entries. For regular: 前年7月 through 当年6月 in order. For revision: the 9 months BEFORE the pay change, then the 3 months after it.
current_remuneration	number	optional	revision only.
fixed_pay_change	string	optional	revision only.
worker_type	string	optional	general = 一般の被保険者 (17-day threshold). part_time_short_hours = 短時間就労者, works shorter hours but meets the three-quarters test (17 days, with a 15-day fallback that exists ONLY in 定時決定). short_time_insured = 短時間労働者 at a 特定適用事業所 (11 days). Defaults to general.
recurring_annually	boolean	required	The swing recurs every year for reasons inherent to the work. Mandatory condition.
employee_consent	boolean	required	The employee has consented. Mandatory condition.

Raw schema

{
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "enum": [
        "regular",
        "revision"
      ],
      "description": "regular = 定時決定の年間平均, revision = 随時改定の年間平均."
    },
    "months": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "month": {
            "description": "YYYY-MM, for readability.",
            "type": "string"
          },
          "remuneration": {
            "description": "regular only: total pay that month.",
            "type": "number"
          },
          "fixed": {
            "description": "revision only: fixed pay that month.",
            "type": "number"
          },
          "non_fixed": {
            "description": "revision only: overtime and other variable pay.",
            "type": "number"
          },
          "payment_basis_days": {
            "type": "number"
          }
        },
        "required": [
          "payment_basis_days"
        ]
      },
      "description": "Exactly 12 entries. For regular: 前年7月 through 当年6月 in order. For revision: the 9 months BEFORE the pay change, then the 3 months after it."
    },
    "current_remuneration": {
      "description": "revision only.",
      "type": "number"
    },
    "fixed_pay_change": {
      "description": "revision only.",
      "type": "string",
      "enum": [
        "increase",
        "decrease"
      ]
    },
    "worker_type": {
      "description": "general = 一般の被保険者 (17-day threshold). part_time_short_hours = 短時間就労者, works shorter hours but meets the three-quarters test (17 days, with a 15-day fallback that exists ONLY in 定時決定). short_time_insured = 短時間労働者 at a 特定適用事業所 (11 days). Defaults to general.",
      "type": "string",
      "enum": [
        "general",
        "part_time_short_hours",
        "short_time_insured"
      ]
    },
    "recurring_annually": {
      "type": "boolean",
      "description": "The swing recurs every year for reasons inherent to the work. Mandatory condition."
    },
    "employee_consent": {
      "type": "boolean",
      "description": "The employee has consented. Mandatory condition."
    }
  },
  "required": [
    "type",
    "months",
    "recurring_annually",
    "employee_consent"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

lookup_standard_remuneration

Maps a monthly amount to its health grade (1-50) and pension grade (1-32), with the standard remuneration each resolves to and whether the pension grade was clamped. Use it to check a grade, not to compute premiums — calculate_payslip does that.

Parameters1

remuneration

number

optional

Monthly remuneration in yen. Omit to get the whole grade table instead of one lookup.

Raw schema

{
  "type": "object",
  "properties": {
    "remuneration": {
      "description": "Monthly remuneration in yen. Omit to get the whole grade table instead of one lookup.",
      "type": "number"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

national_insurance

For anyone outside employee cover: the self-employed, freelancers, people between jobs. Use this instead of calculate_payslip when the person is not an employee. Running a freelancer through the payslip returns a figure computed under a different scheme entirely, with nothing in the answer to say so. If you are unsure which side someone is on, judge_worker_type decides it. The two schemes differ in how far they can be answered, and the difference matters. 国民年金法第87条 makes the pension contribution a statutory amount times a revision rate set each year by cabinet order — the same figure everywhere in the country, flat regardless of income. That comes back as a number. 国民健康保険法第76条 leaves the health contribution to each municipality, collected from the head of the household, and states no figure at all. Around 1,700 municipalities each set their own income-based, per-person and per-household components and their own ceilings. There is no national number to give. Do not estimate one, and do not present a figure from one city as though it were general — tell the person to ask their own municipality, which is what the response says. Exemptions, deferrals and the student special case all change what is actually paid, and whether they apply turns on income and household. Those are not judged here.

Parameters3

as_of	string	optional	Date to judge, YYYY-MM-DD. Outside the year carried it refuses rather than quoting a stale figure.
months	number	optional	Months to total. The contribution is flat, so this multiplies.
supplementary	boolean	optional	Add the optional 付加保険料 of 400 a month, which raises the basic old-age pension later.

Raw schema

{
  "type": "object",
  "properties": {
    "as_of": {
      "description": "Date to judge, YYYY-MM-DD. Outside the year carried it refuses rather than quoting a stale figure.",
      "type": "string"
    },
    "months": {
      "description": "Months to total. The contribution is flat, so this multiplies.",
      "type": "number"
    },
    "supplementary": {
      "description": "Add the optional 付加保険料 of 400 a month, which raises the basic old-age pension later.",
      "type": "boolean"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

calculate_annual_cost

What one employee costs an employer over a year, bonuses included. Reach for this rather than multiplying a payslip by twelve, because the two do not agree once a bonus is paid. 健康保険法第45条 caps the standard bonus cumulatively across the year — 5,730,000 from 1 April to 31 March — so the same bonus costs a different amount depending on where it falls, and once the year is used up later bonuses carry no health premium. 厚生年金保険法第24条の4 caps at 1,500,000 per payment with no yearly total, so pension keeps charging where health has stopped. Pass bonuses in the order they are paid: the health allowance fills from the first one. Each row comes back with what was counted, whether it was cut, and how much of the year remains, so the answer can be explained rather than just quoted. Income tax here is the monthly figure times twelve. Bonus withholding is a separate calculation (calculate_bonus with include_tax) and the year-end adjustment is a separate tool (calculate_year_end_adjustment) — say so rather than presenting this as take-home pay for the year.

Parameters11

prefecture	string	required	Prefecture of the employer's 適用事業所 — English ("Tokyo"), Japanese ("東京" or "東京都"), or JIS code 1-47. Health insurance rates differ by prefecture; pension does not.
monthly_salary	number	required	Gross monthly pay in yen.
age	number	optional	Either this or birth_date is required.
birth_date	string	optional	Date of birth, YYYY-MM-DD. Strongly preferred over `age`: 年齢計算ニ関スル法律 puts the attainment of an age on the day before the birthday, so someone born on the 1st of a month crosses a threshold in the previous month and their premium changes a month earlier than a naive calculation gives.
bonuses	array	optional	Each bonus in yen, in the order paid. The health cap fills from the first.
fiscal_year	number	optional	Year the 1 April to 31 March window starts. Defaults from the current date.
standard_remuneration	number	optional	The 標準報酬月額 fixed by 算定基礎届, if known. Without it the grade is derived from the pay given.
workers_comp_type	string	optional	事業の種類の番号. Charged on bonuses as well, being levied on total wages.
business_type	string	optional
dependants	number	optional
resident_tax	number	optional	Monthly resident tax, multiplied by twelve as given. It is never derived here.

Raw schema

{
  "type": "object",
  "properties": {
    "prefecture": {
      "type": "string",
      "description": "Prefecture of the employer's 適用事業所 — English (\"Tokyo\"), Japanese (\"東京\" or \"東京都\"), or JIS code 1-47. Health insurance rates differ by prefecture; pension does not."
    },
    "monthly_salary": {
      "type": "number",
      "description": "Gross monthly pay in yen."
    },
    "age": {
      "description": "Either this or birth_date is required.",
      "type": "number"
    },
    "birth_date": {
      "description": "Date of birth, YYYY-MM-DD. Strongly preferred over `age`: 年齢計算ニ関スル法律 puts the attainment of an age on the day *before* the birthday, so someone born on the 1st of a month crosses a threshold in the previous month and their premium changes a month earlier than a naive calculation gives.",
      "type": "string"
    },
    "bonuses": {
      "description": "Each bonus in yen, in the order paid. The health cap fills from the first.",
      "type": "array",
      "items": {
        "type": "number"
      }
    },
    "fiscal_year": {
      "description": "Year the 1 April to 31 March window starts. Defaults from the current date.",
      "type": "number"
    },
    "standard_remuneration": {
      "description": "The 標準報酬月額 fixed by 算定基礎届, if known. Without it the grade is derived from the pay given.",
      "type": "number"
    },
    "workers_comp_type": {
      "description": "事業の種類の番号. Charged on bonuses as well, being levied on total wages.",
      "type": "string"
    },
    "business_type": {
      "type": "string",
      "enum": [
        "general",
        "agriculture_forestry_fishery_sake",
        "construction"
      ]
    },
    "dependants": {
      "type": "number"
    },
    "resident_tax": {
      "description": "Monthly resident tax, multiplied by twelve as given. It is never derived here.",
      "type": "number"
    }
  },
  "required": [
    "prefecture",
    "monthly_salary"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

judge_annual_leave

Works out how many days of paid leave someone has been granted, and whether the employer still owes the five days it must direct. 労働基準法第39条 grants ten working days once six months of service are complete and attendance reaches eighty per cent of all working days, then adds one, two, four, six, eight and ten days in the years that follow. The ceiling everyone quotes as twenty is not in the article: it is the ten of the first grant plus the ten added from the sixth year. Someone under thirty hours a week working four days or fewer takes a smaller table from 施行規則第24条の3. Thirty hours is where it turns — at or above it the ordinary grant applies no matter how few days are worked, and treating such a person as part-time under-grants them. Ask for both the weekly days and the weekly hours; one without the other cannot settle it. Where ten or more days are granted, 第39条第7項 requires the employer to fix the timing of five of them within the year, and days the employee took of their own accord count toward it. A grant lapses two years after it is made (第115条), so one year carries over. The attendance figure is a question about the workplace: leave for a work injury, maternity, childcare and paid leave already taken all count as attendance. Ask for a rate that has been worked out rather than dividing days present by days in the year. Without one the tool reports the eighty per cent test as not judged rather than assuming it passed.

Parameters7

hired_on	string	required	Date of hire, YYYY-MM-DD. Grants fall six months later, then annually.
as_of	string	optional	Date to judge against, YYYY-MM-DD. Defaults to today.
attendance_rate	number	optional	Attendance as a fraction of all working days, 0 to 1. Eighty per cent or more grants.
weekly_days	number	optional	週所定労働日数.
weekly_hours	number	optional	週所定労働時間. Thirty or more takes the ordinary grant whatever the day count.
annual_days	number	optional	一年間の所定労働日数, in place of weekly_days.
days_taken	number	optional	Days already taken in the current year, counted against the five the employer must direct.

Raw schema

{
  "type": "object",
  "properties": {
    "hired_on": {
      "type": "string",
      "description": "Date of hire, YYYY-MM-DD. Grants fall six months later, then annually."
    },
    "as_of": {
      "description": "Date to judge against, YYYY-MM-DD. Defaults to today.",
      "type": "string"
    },
    "attendance_rate": {
      "description": "Attendance as a fraction of all working days, 0 to 1. Eighty per cent or more grants.",
      "type": "number"
    },
    "weekly_days": {
      "description": "週所定労働日数.",
      "type": "number"
    },
    "weekly_hours": {
      "description": "週所定労働時間. Thirty or more takes the ordinary grant whatever the day count.",
      "type": "number"
    },
    "annual_days": {
      "description": "一年間の所定労働日数, in place of weekly_days.",
      "type": "number"
    },
    "days_taken": {
      "description": "Days already taken in the current year, counted against the five the employer must direct.",
      "type": "number"
    }
  },
  "required": [
    "hired_on"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

judge_worker_type

Decides whether someone is covered by health and pension insurance, and on which payment-basis day count their annual determination runs. Call this before decide_regular_remuneration or judge_monthly_revision whenever the person is anything other than plainly full-time. Those tools take a worker_type, and guessing it changes a real number: the determination counts months of seventeen payment-basis days for an ordinary employee and eleven for a 短時間労働者. Get the classification wrong and the answer is wrong with no sign of it. 健康保険法第3条第1項第9号 covers anyone whose weekly hours and monthly days reach three-quarters of a comparable full-time worker. Below that, four further tests decide it: twenty hours a week, 88,000 yen a month, not a student, and a workplace of at least fifty-one insured people. The engagement must also be expected to run past two months. The 88,000 figure leaves out overtime, bonuses, commuting and family allowances. Folding those in is the usual route to a wrong answer, so ask for 所定内賃金 specifically rather than total pay. What counts as a comparable full-time worker, and whether someone is a student for this purpose, are facts about the workplace and the person. Ask rather than assume; the tool applies the tests to what you pass and names any it could not evaluate.

Parameters8

weekly_hours	number	required	1週間の所定労働時間.
normal_weekly_hours	number	optional	The same figure for a comparable full-time worker at that workplace. Defaults to 40.
monthly_days	number	optional	1月間の所定労働日数. The article tests days as well as hours, so pass both where known.
normal_monthly_days	number	optional	The same figure for a comparable full-time worker.
monthly_wage	number	optional	所定内賃金の月額 — excluding overtime, bonuses, commuting and family allowances.
is_student	boolean	optional	A student under 学校教育法. Night courses and those with a graduation certificate are exceptions.
workplace_insured_count	number	optional	Pension-insured headcount at the employer, not counting short-time workers.
employment_months	number	optional	How long the engagement is expected to run, in months.

Raw schema

{
  "type": "object",
  "properties": {
    "weekly_hours": {
      "type": "number",
      "description": "1週間の所定労働時間."
    },
    "normal_weekly_hours": {
      "description": "The same figure for a comparable full-time worker at that workplace. Defaults to 40.",
      "type": "number"
    },
    "monthly_days": {
      "description": "1月間の所定労働日数. The article tests days as well as hours, so pass both where known.",
      "type": "number"
    },
    "normal_monthly_days": {
      "description": "The same figure for a comparable full-time worker.",
      "type": "number"
    },
    "monthly_wage": {
      "description": "所定内賃金の月額 — excluding overtime, bonuses, commuting and family allowances.",
      "type": "number"
    },
    "is_student": {
      "description": "A student under 学校教育法. Night courses and those with a graduation certificate are exceptions.",
      "type": "boolean"
    },
    "workplace_insured_count": {
      "description": "Pension-insured headcount at the employer, not counting short-time workers.",
      "type": "number"
    },
    "employment_months": {
      "description": "How long the engagement is expected to run, in months.",
      "type": "number"
    }
  },
  "required": [
    "weekly_hours"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

check_insurance_eligibility

The single most expensive month-end mistake in Japanese payroll, and one an assistant will get wrong from memory. Coverage ends the day AFTER the last day worked, not on it. So an employee leaving on the LAST day of a month loses coverage on the 1st of the next month, and still owes that month's premium — while leaving one day earlier means no premium for the month at all. A full month of both employee and employer premium turns on a single day. Always check here rather than reasoning it out.

Parameters3

month	string	optional	Month to judge, YYYY-MM or a full date. Defaults to today.
joined_on	string	optional	First day of employment, YYYY-MM-DD.
left_on	string	optional	Last day actually worked, YYYY-MM-DD — not the day after.

Raw schema

{
  "type": "object",
  "properties": {
    "month": {
      "description": "Month to judge, YYYY-MM or a full date. Defaults to today.",
      "type": "string"
    },
    "joined_on": {
      "description": "First day of employment, YYYY-MM-DD.",
      "type": "string"
    },
    "left_on": {
      "description": "Last day actually worked, YYYY-MM-DD — not the day after.",
      "type": "string"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

check_leave_exemption

Maternity and childcare leave look alike and behave differently. Maternity leave has no day-count test and exempts bonus premiums unconditionally; childcare leave gained a 14-day rule in October 2022 and exempts bonus premiums only when the leave exceeds one month. Two results catch people out and are worth checking rather than assuming: a leave that starts and ends inside one month exempts nothing by itself under the main rule, while a SINGLE day of leave on the last day of a month is exempt. Employment insurance is never exempt — it is charged on wages actually paid.

Parameters4

kind	string	required	産前産後休業 or 育児休業等.
start	string	required	First day of leave, YYYY-MM-DD.
end	string	required	Last day of leave, YYYY-MM-DD.
worked_days	number	optional	出生時育児休業 only: days worked during the leave, which come off the 14-day count.

Raw schema

{
  "type": "object",
  "properties": {
    "kind": {
      "type": "string",
      "enum": [
        "maternity",
        "childcare"
      ],
      "description": "産前産後休業 or 育児休業等."
    },
    "start": {
      "type": "string",
      "description": "First day of leave, YYYY-MM-DD."
    },
    "end": {
      "type": "string",
      "description": "Last day of leave, YYYY-MM-DD."
    },
    "worked_days": {
      "description": "出生時育児休業 only: days worked during the leave, which come off the 14-day count.",
      "type": "number"
    }
  },
  "required": [
    "kind",
    "start",
    "end"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_age_milestones

Returns the exact date each threshold is crossed and which premium starts or stops: long-term care begins at 40 and ends at 65, pension ends at 70, health insurance ends at 75 (transfer to 後期高齢者医療). Compute this here rather than by subtracting years. Under 年齢計算ニ関スル法律 an age is reached the day BEFORE the birthday, so someone born on the 1st of a month attains it in the previous month and their premium changes a month earlier than expected.

Parameters2

birth_date	string	required	Date of birth, YYYY-MM-DD.
as_of	string	optional	Date to judge against. Defaults to today.

Raw schema

{
  "type": "object",
  "properties": {
    "birth_date": {
      "type": "string",
      "description": "Date of birth, YYYY-MM-DD."
    },
    "as_of": {
      "description": "Date to judge against. Defaults to today.",
      "type": "string"
    }
  },
  "required": [
    "birth_date"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

calculate_year_end_adjustment

Year-end adjustment (年末調整) for 2026 from the National Tax Agency's 令和8年分 booklet: the printed 給与所得控除後の給与等の金額 table (1,103 rows), the income-adjustment deduction, social/life/earthquake insurance deductions, spouse, specified-relative (19-22 with income), dependant, disability, widow/single-parent/student and basic deductions, the year-end tax bracket table, the housing-loan credit and the 2.1% reconstruction surtax. Returns every box of the 源泉徴収簿 (⑦ to ㉗) and whether the difference is a refund or a collection. Pay figures are for the whole calendar year, bonuses included. Pass only what the employee declared on their forms; the tool does not assume a spouse, dependants or insurance. Anyone paid 20,000,000 yen or more is outside 年末調整 and the tool says so. Medical, donation and casualty-loss deductions are not part of 年末調整 (they need a tax return) and resident tax is never involved.

Parameters16

total_pay	integer	required	Total pay for the year including bonuses (⑦).
withheld_tax	integer	required	Income tax withheld during the year (⑧).
social_insurance	integer	required	Social insurance premiums deducted from pay during the year (⑫).
social_insurance_declared	integer	optional	Social insurance the employee paid themselves and declared, e.g. 国民年金 (⑬).
mutual_aid	integer	optional	小規模企業共済等掛金 (⑭).
life_insurance	object	optional	Premiums PAID this year by category (new = contracts from 2012-01-01). The deduction is computed here.
earthquake_insurance	object	optional	Earthquake insurance and 旧長期損害保険 premiums paid.
spouse	any	optional
dependants	object	optional
disabilities	object	optional	Counts of 障害者 / 特別障害者 / 同居特別障害者 among the employee, spouse and dependants.
flags	object	optional
specified_relatives	array	optional	特定親族 (19-22 with 合計所得金額 over 620,000): one income figure per person.
housing_loan_credit	integer	optional	住宅借入金等特別控除額 (㉔), from the certificate.
other_income	integer	optional	Income other than this pay, for the basic and spouse deduction bands.
income_adjustment	boolean	optional	Force the 所得金額調整控除 on or off. Omit to derive it from pay > 8,500,000 and the under_23 / disability inputs.
tax_return	object	optional	Deductions that only a tax return can take (medical, self-medication, donations, casualty loss). They are NOT part of 年末調整; pass them to get a separate "if the employee files a return" estimate.

Raw schema

{
  "type": "object",
  "properties": {
    "total_pay": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991,
      "description": "Total pay for the year including bonuses (⑦)."
    },
    "withheld_tax": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991,
      "description": "Income tax withheld during the year (⑧)."
    },
    "social_insurance": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991,
      "description": "Social insurance premiums deducted from pay during the year (⑫)."
    },
    "social_insurance_declared": {
      "description": "Social insurance the employee paid themselves and declared, e.g. 国民年金 (⑬).",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "mutual_aid": {
      "description": "小規模企業共済等掛金 (⑭).",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "life_insurance": {
      "description": "Premiums PAID this year by category (new = contracts from 2012-01-01). The deduction is computed here.",
      "type": "object",
      "properties": {
        "new_general": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        "old_general": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        "care_medical": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        "new_pension": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        "old_pension": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        }
      }
    },
    "earthquake_insurance": {
      "description": "Earthquake insurance and 旧長期損害保険 premiums paid.",
      "type": "object",
      "properties": {
        "earthquake": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        "old_long_term": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        }
      }
    },
    "spouse": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "income": {
              "type": "integer",
              "minimum": 0,
              "maximum": 9007199254740991,
              "description": "Spouse's 合計所得金額 (not gross pay)."
            },
            "age_70_or_over": {
              "type": "boolean"
            }
          },
          "required": [
            "income"
          ]
        },
        {
          "type": "null"
        }
      ]
    },
    "dependants": {
      "type": "object",
      "properties": {
        "general": {
          "description": "一般の控除対象扶養親族 (16+ excluding the categories below).",
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        "specified": {
          "description": "特定扶養親族 (19-22, income ≤ 620,000).",
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        "elderly": {
          "description": "老人扶養親族 (70+) not a cohabiting parent.",
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        "elderly_cohabiting_parent": {
          "description": "同居老親等.",
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        "under_23": {
          "description": "Dependants under 23. Drives the income-adjustment deduction and the life-insurance special rule.",
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        }
      }
    },
    "disabilities": {
      "description": "Counts of 障害者 / 特別障害者 / 同居特別障害者 among the employee, spouse and dependants.",
      "type": "object",
      "properties": {
        "general": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        "special": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        "special_cohabiting": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        }
      }
    },
    "flags": {
      "type": "object",
      "properties": {
        "widow": {
          "type": "boolean"
        },
        "single_parent": {
          "type": "boolean"
        },
        "working_student": {
          "type": "boolean"
        },
        "self_special_disabled": {
          "type": "boolean"
        }
      }
    },
    "specified_relatives": {
      "description": "特定親族 (19-22 with 合計所得金額 over 620,000): one income figure per person.",
      "type": "array",
      "items": {
        "type": "integer",
        "minimum": 0,
        "maximum": 9007199254740991
      }
    },
    "housing_loan_credit": {
      "description": "住宅借入金等特別控除額 (㉔), from the certificate.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "other_income": {
      "description": "Income other than this pay, for the basic and spouse deduction bands.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "income_adjustment": {
      "description": "Force the 所得金額調整控除 on or off. Omit to derive it from pay > 8,500,000 and the under_23 / disability inputs.",
      "type": "boolean"
    },
    "tax_return": {
      "description": "Deductions that only a tax return can take (medical, self-medication, donations, casualty loss). They are NOT part of 年末調整; pass them to get a separate \"if the employee files a return\" estimate.",
      "type": "object",
      "properties": {
        "medical_expenses": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        "medical_reimbursed": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        "self_medication": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        "donations": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        "casualty_loss": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        "disaster_related_expense": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        }
      }
    }
  },
  "required": [
    "total_pay",
    "withheld_tax",
    "social_insurance"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

estimate_resident_tax

Estimate of next fiscal year's resident tax (住民税: 道府県民税 + 市町村民税 + 森林環境税) from the previous year's income and the municipality: employment income from the NTA table for that year, resident-tax deductions (basic 430,000, spouse 330,000, dependants 330,000/450,000/380,000, life insurance capped at 70,000), the 10% income levy split 4%/6% (2%/8% in designated cities), the adjustment credit, the non-taxable thresholds (35万円 × persons + 10万円 + 21万円, with the 級地 rate), ふるさと納税 basic and special credits (special capped at 20% of the income levy), the housing-loan carry-over, per-capita amounts including every prefecture's surtax (37 of 47 have one; Kanagawa also adds 0.025% to the income levy) and the city rules of 横浜市 (+900), 神戸市 (+400) and 名古屋市 (5% cut). Matches the published 令和8年度 worked examples of Yokohama and Nagoya to the yen. It is an ESTIMATE: the municipality decides the amount and the employer deducts what the 特別徴収税額通知書 says. Say so. income_year is the year the income was earned (2025 for the fiscal-2026 tax). Pass grade_level (級地 1-3) when known; it changes the per-capita exemption.

Parameters26

prefecture	string	required	Prefecture of the employer's 適用事業所 — English ("Tokyo"), Japanese ("東京" or "東京都"), or JIS code 1-47. Health insurance rates differ by prefecture; pension does not.
city	string	optional	Municipality in Japanese, e.g. 横浜市. Used for designated-city rates and the three city rules held.
designated_city	boolean	optional	Set when the city is one of the 20 指定都市 and you did not pass city.
grade_level	integer	optional	級地 (1, 2 or 3) for the per-capita exemption threshold.
income_year	integer	required	Year the income was earned: 2025 (fiscal 2026 tax) or 2026 (fiscal 2027 estimate).
salary	integer	optional	Gross employment income for the year, bonuses included.
total_income	integer	optional	Use instead of salary when the income is not (only) employment income: 合計所得金額 excluding salary.
other_income	integer	optional
social_insurance	integer	optional	Social insurance paid in the year.
mutual_aid	integer	optional
life_insurance	object	optional	Premiums PAID; the resident-tax deduction (cap 70,000) is computed here.
earthquake_insurance	object	optional
medical_expenses	integer	optional
medical_reimbursed	integer	optional
casualty_loss	integer	optional
disaster_related_expense	integer	optional
spouse	any	optional	Spouse's 合計所得金額 for the year (0 if none).
dependants	object	optional
disabilities	object	optional
flags	object	optional
specified_relatives	array	optional
income_adjustment	boolean	optional
furusato_donations	integer	optional	ふるさと納税 paid in the year.
other_donations	integer	optional	Other qualifying donations (basic 10% credit only).
housing_loan_unused	integer	optional	Housing-loan credit the income tax could not absorb.
housing_loan_cap	string	optional	Cap rule for the resident-tax part: 5% (max 97,500) or 7% (max 136,500).

Raw schema

{
  "type": "object",
  "properties": {
    "prefecture": {
      "type": "string",
      "description": "Prefecture of the employer's 適用事業所 — English (\"Tokyo\"), Japanese (\"東京\" or \"東京都\"), or JIS code 1-47. Health insurance rates differ by prefecture; pension does not."
    },
    "city": {
      "description": "Municipality in Japanese, e.g. 横浜市. Used for designated-city rates and the three city rules held.",
      "type": "string"
    },
    "designated_city": {
      "description": "Set when the city is one of the 20 指定都市 and you did not pass city.",
      "type": "boolean"
    },
    "grade_level": {
      "description": "級地 (1, 2 or 3) for the per-capita exemption threshold.",
      "type": "integer",
      "minimum": 1,
      "maximum": 3
    },
    "income_year": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991,
      "description": "Year the income was earned: 2025 (fiscal 2026 tax) or 2026 (fiscal 2027 estimate)."
    },
    "salary": {
      "description": "Gross employment income for the year, bonuses included.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "total_income": {
      "description": "Use instead of salary when the income is not (only) employment income: 合計所得金額 excluding salary.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "other_income": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "social_insurance": {
      "description": "Social insurance paid in the year.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "mutual_aid": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "life_insurance": {
      "description": "Premiums PAID; the resident-tax deduction (cap 70,000) is computed here.",
      "type": "object",
      "properties": {
        "new_general": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        "old_general": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        "care_medical": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        "new_pension": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        "old_pension": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        }
      }
    },
    "earthquake_insurance": {
      "type": "object",
      "properties": {
        "earthquake": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        "old_long_term": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        }
      }
    },
    "medical_expenses": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "medical_reimbursed": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "casualty_loss": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "disaster_related_expense": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "spouse": {
      "description": "Spouse's 合計所得金額 for the year (0 if none).",
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "income": {
              "type": "integer",
              "minimum": 0,
              "maximum": 9007199254740991
            },
            "age_70_or_over": {
              "type": "boolean"
            }
          },
          "required": [
            "income"
          ]
        },
        {
          "type": "null"
        }
      ]
    },
    "dependants": {
      "type": "object",
      "properties": {
        "general": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        "specified": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        "elderly": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        "elderly_cohabiting_parent": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        "under_23": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        "under_16": {
          "description": "Dependants under 16: no deduction, but they count for the exemption thresholds.",
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        }
      }
    },
    "disabilities": {
      "type": "object",
      "properties": {
        "general": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        "special": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        "special_cohabiting": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        }
      }
    },
    "flags": {
      "type": "object",
      "properties": {
        "widow": {
          "type": "boolean"
        },
        "single_parent": {
          "type": "boolean"
        },
        "single_parent_father": {
          "type": "boolean"
        },
        "working_student": {
          "type": "boolean"
        },
        "self_special_disabled": {
          "type": "boolean"
        },
        "minor": {
          "type": "boolean"
        }
      }
    },
    "specified_relatives": {
      "type": "array",
      "items": {
        "type": "integer",
        "minimum": 0,
        "maximum": 9007199254740991
      }
    },
    "income_adjustment": {
      "type": "boolean"
    },
    "furusato_donations": {
      "description": "ふるさと納税 paid in the year.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "other_donations": {
      "description": "Other qualifying donations (basic 10% credit only).",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "housing_loan_unused": {
      "description": "Housing-loan credit the income tax could not absorb.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "housing_loan_cap": {
      "description": "Cap rule for the resident-tax part: 5% (max 97,500) or 7% (max 136,500).",
      "type": "string",
      "enum": [
        "five_percent",
        "seven_percent"
      ]
    }
  },
  "required": [
    "prefecture",
    "income_year"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_insurance_rates

Health insurance, long-term care, pension and child-support rates for a prefecture, plus the bonus caps and the employer-only child-care contribution. Health rates differ by prefecture and change each March; pension is national. Add business_type for the employment insurance rates, which change each April — pass as_of to get the rate in force on that date (FY2025 and FY2026 are held; March is the month where health rates are already the new year's while employment insurance is still the old year's).

Parameters3

prefecture	string	required	Prefecture of the employer's 適用事業所 — English ("Tokyo"), Japanese ("東京" or "東京都"), or JIS code 1-47. Health insurance rates differ by prefecture; pension does not.
business_type	string	optional	Include employment insurance rates for this band.
as_of	string	optional	ISO date. Selects the employment insurance fiscal year (April to March). A date before the held tables returns out_of_coverage rather than a guess.

Raw schema

{
  "type": "object",
  "properties": {
    "prefecture": {
      "type": "string",
      "description": "Prefecture of the employer's 適用事業所 — English (\"Tokyo\"), Japanese (\"東京\" or \"東京都\"), or JIS code 1-47. Health insurance rates differ by prefecture; pension does not."
    },
    "business_type": {
      "description": "Include employment insurance rates for this band.",
      "type": "string",
      "enum": [
        "general",
        "agriculture_forestry_fishery_sake",
        "construction"
      ]
    },
    "as_of": {
      "description": "ISO date. Selects the employment insurance fiscal year (April to March). A date before the held tables returns out_of_coverage rather than a guess.",
      "type": "string"
    }
  },
  "required": [
    "prefecture"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_minimum_wage

Hourly 地域別最低賃金 for a prefecture. Revisions take effect prefecture by prefecture from October, on different days, so a date matters — pass one when checking a past payroll rather than assuming the current rate applied. History runs back to FY2002.

Parameters4

prefecture	string	required	Prefecture of the employer's 適用事業所 — English ("Tokyo"), Japanese ("東京" or "東京都"), or JIS code 1-47. Health insurance rates differ by prefecture; pension does not.
date	string	optional	YYYY-MM-DD. Defaults to the rate currently in force.
as_of	string	optional	Alias for date. YYYY-MM-DD.
history	boolean	optional	Return the full history instead of one date.

Raw schema

{
  "type": "object",
  "properties": {
    "prefecture": {
      "type": "string",
      "description": "Prefecture of the employer's 適用事業所 — English (\"Tokyo\"), Japanese (\"東京\" or \"東京都\"), or JIS code 1-47. Health insurance rates differ by prefecture; pension does not."
    },
    "date": {
      "description": "YYYY-MM-DD. Defaults to the rate currently in force.",
      "type": "string"
    },
    "as_of": {
      "description": "Alias for date. YYYY-MM-DD.",
      "type": "string"
    },
    "history": {
      "description": "Return the full history instead of one date.",
      "type": "boolean"
    }
  },
  "required": [
    "prefecture"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

business_days

Count business days in a range, shift a date by N business days, or check one date. Covers 1955-2027 including substitute holidays, 国民の休日 (a weekday that is a holiday only because it sits between two others) and one-off imperial events, so the awkward years are right and not only the tidy ones. Set calendar to "bank" for the statutory banking calendar (銀行法施行令第5条), which is also closed 31 December to 3 January — relevant for payment due dates.

Parameters7

operation	string	required	count = business days between two dates; shift = move a date by N business days; check = classify one date; list = holidays in a year or range.
from	string	optional	Start date, YYYY-MM-DD. For count and list.
to	string	optional	End date, YYYY-MM-DD. For count and list.
date	string	optional	The date, YYYY-MM-DD. For shift and check.
days	number	optional	Business days to move; negative goes back. For shift.
year	number	optional	Year. For list.
calendar	string	optional	Defaults to standard.

Raw schema

{
  "type": "object",
  "properties": {
    "operation": {
      "type": "string",
      "enum": [
        "count",
        "shift",
        "check",
        "list"
      ],
      "description": "count = business days between two dates; shift = move a date by N business days; check = classify one date; list = holidays in a year or range."
    },
    "from": {
      "description": "Start date, YYYY-MM-DD. For count and list.",
      "type": "string"
    },
    "to": {
      "description": "End date, YYYY-MM-DD. For count and list.",
      "type": "string"
    },
    "date": {
      "description": "The date, YYYY-MM-DD. For shift and check.",
      "type": "string"
    },
    "days": {
      "description": "Business days to move; negative goes back. For shift.",
      "type": "number"
    },
    "year": {
      "description": "Year. For list.",
      "type": "number"
    },
    "calendar": {
      "description": "Defaults to standard.",
      "type": "string",
      "enum": [
        "standard",
        "bank"
      ]
    }
  },
  "required": [
    "operation"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

validate_invoice_numbers_batch

Checks the National Tax Agency check digit on many qualified-invoice registration numbers in one call. Be careful how you report the result. A passing check digit means the shape of the number is right and nothing more. 消費税法第57条の2 provides both for the Commissioner to revoke a registration and for one to lapse, so a well-formed number can be unregistered, revoked or expired. Never tell someone a number is valid, verified or confirmed on the strength of this — say the format checks out, and that the register itself was not consulted. What it does earn is elimination. Anything failing on shape needs no lookup at all, so the list taken to 国税庁「適格請求書発行事業者公表サイト」 gets shorter. That site publishes the revocation and lapse dates, and offers a bulk download and a Web-API for large lists. Duplicates come back as given rather than folded together, and each result carries the index of its input, so rows line up with the caller list they came from.

Parameters1

numbers

array

required

Registration numbers as written, including the leading T. Up to 1000 per call.

Raw schema

{
  "type": "object",
  "properties": {
    "numbers": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Registration numbers as written, including the leading T. Up to 1000 per call."
    }
  },
  "required": [
    "numbers"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

validate_corporate_number

Checks the National Tax Agency check digit on a 13-digit 法人番号, or on a qualified invoice registration number (the same 13 digits prefixed with T). This proves the number is well formed. It does NOT prove the number is registered, and it does not identify the holder: sole proprietors receive invoice numbers that satisfy exactly the same rule, so a passing check digit must not be reported as evidence of a corporation. To confirm registration, use the National Tax Agency's own lookup.

Parameters2

number	string	optional	13 digits, or T followed by 13 digits.
base	string	optional	The 12-digit 会社法人等番号 instead, to compute its check digit and get the 13-digit 法人番号. Use this when registering, not when checking.

Raw schema

{
  "type": "object",
  "properties": {
    "number": {
      "description": "13 digits, or T followed by 13 digits.",
      "type": "string"
    },
    "base": {
      "description": "The 12-digit 会社法人等番号 instead, to compute its check digit and get the 13-digit 法人番号. Use this when registering, not when checking.",
      "type": "string"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

consumption_tax

The consumption tax rate in force on a date, with the national and local parts, and the reduced 8% rate for food and newspapers. Pass amount to have the tax worked out. Japan changed the rate four times since 1989 (3% → 5% → 8% → 10%), and the reduced rate has existed only since 2019-10-01. A back-dated invoice or a credit note against an old sale is charged at the rate of the original transaction, not today's, so the date matters more often than people expect. Set history to see every change with its statute.

Parameters5

as_of	string	optional	Alias for date. YYYY-MM-DD.
date	string	optional	YYYY-MM-DD. The rate in force on that day. Defaults to today.
amount	number	optional	Tax-exclusive amount in yen, to compute the tax.
reduced	boolean	optional	True for the 8% reduced rate — food and drink excluding alcohol and eating out, and subscribed newspapers issued twice a week or more (平成28年法律第15号).
history	boolean	optional	Return every rate change since 1989 instead of one date.

Raw schema

{
  "type": "object",
  "properties": {
    "as_of": {
      "description": "Alias for date. YYYY-MM-DD.",
      "type": "string"
    },
    "date": {
      "description": "YYYY-MM-DD. The rate in force on that day. Defaults to today.",
      "type": "string"
    },
    "amount": {
      "description": "Tax-exclusive amount in yen, to compute the tax.",
      "type": "number"
    },
    "reduced": {
      "description": "True for the 8% reduced rate — food and drink excluding alcohol and eating out, and subscribed newspapers issued twice a week or more (平成28年法律第15号).",
      "type": "boolean"
    },
    "history": {
      "description": "Return every rate change since 1989 instead of one date.",
      "type": "boolean"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_statute_text

Returns the full text of a Japanese statutory provision, as published by e-Gov. The judgement tools name the statute or notice their answer rests on, but not its words. Use this to quote the provision itself — a citation the reader can check beats a citation they have to take on trust, and Japanese payroll advice is routinely wrong in ways that only reading the article reveals. Only the provisions this API cites are bundled (about 28 across 8 laws); call it with no ref to list them. Abbreviations as practitioners write them (健保法43条, 厚年法81条の2, 徴収法11条), a missing 第, and paragraph-level references all resolve to the article. For anything outside this set, say so rather than reciting it from memory.

Parameters1

ref

string

optional

A citation such as "健康保険法第43条". Omit to list every provision available.

Raw schema

{
  "type": "object",
  "properties": {
    "ref": {
      "description": "A citation such as \"健康保険法第43条\". Omit to list every provision available.",
      "type": "string"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

calculate_overtime_pay

Works out statutory premium pay under 労働基準法第37条 — overtime, night work and work on a statutory holiday. The rates do not simply add up, and getting this wrong under-pays wages. A night premium stacks on top: overtime at night is 1.25 + 0.25 = 1.5, holiday work at night is 1.35 + 0.25 = 1.6. But a statutory holiday carries no overtime premium at all — a day with no duty to work has nothing to exceed — so holiday hours are 1.35, never 1.6 by adding overtime. Overtime beyond sixty hours in a month is 50%, and the deferral that exempted small employers ended on 1 April 2023, so headcount no longer matters. Rounding follows 昭和63年基発第150号, which rounds each category separately rather than once at the end, so the total will not always match a single multiplication. Rounding the hours themselves down is a breach of 労基法第24条 and this tool will not do it. base_monthly_pay must exclude the seven allowances that 労基法37条5項 and 施行規則21条 enumerate exhaustively, and only those. Exclusion turns on substance, not the name: a 「家族手当」 paid at a flat rate regardless of dependants cannot be excluded. The response lists all seven. Do not guess at whether an allowance qualifies — ask which way it is paid.

Parameters6

base_monthly_pay	number	required	Monthly pay forming the premium base, after removing any of the seven excludable allowances.
monthly_scheduled_hours	number	required	月平均所定労働時間 — annual scheduled working days times daily hours, divided by twelve.
overtime_hours	number	optional	Statutory overtime hours, excluding work on a statutory holiday.
night_hours	number	optional	How many of those hours fell between 22:00 and 05:00.
holiday_hours	number	optional	Hours worked on a statutory holiday.
holiday_night_hours	number	optional	How many of those fell between 22:00 and 05:00.

Raw schema

{
  "type": "object",
  "properties": {
    "base_monthly_pay": {
      "type": "number",
      "description": "Monthly pay forming the premium base, after removing any of the seven excludable allowances."
    },
    "monthly_scheduled_hours": {
      "type": "number",
      "description": "月平均所定労働時間 — annual scheduled working days times daily hours, divided by twelve."
    },
    "overtime_hours": {
      "description": "Statutory overtime hours, excluding work on a statutory holiday.",
      "type": "number"
    },
    "night_hours": {
      "description": "How many of those hours fell between 22:00 and 05:00.",
      "type": "number"
    },
    "holiday_hours": {
      "description": "Hours worked on a statutory holiday.",
      "type": "number"
    },
    "holiday_night_hours": {
      "description": "How many of those fell between 22:00 and 05:00.",
      "type": "number"
    }
  },
  "required": [
    "base_monthly_pay",
    "monthly_scheduled_hours"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

commuting_allowance_exemption

Works out how much of a commuting allowance escapes income tax, and states the amount that still counts as remuneration for social insurance. These are two different bases, and that asymmetry is the part people get wrong. Social insurance counts a commuting allowance in full — it is 報酬 under 健康保険法第3条第5項 regardless of the tax treatment — while income tax is charged only on what exceeds the ceiling. So a 15,000 yen allowance on a 300,000 yen salary makes the standard-remuneration basis 315,000 and the taxable pay 300,000. Never answer with a single figure that is meant to serve both. The ceiling is 150,000 a month for public transport. For a car or bicycle it is set by one-way distance, with nothing exempt under two kilometres, and up to 5,000 more a month when the employee pays for parking. Using both adds them together, still capped at 150,000. Do not answer this from memory. The table moved twice in twelve months: a cabinet order promulgated 19 November 2025 raised every band over ten kilometres and applied retroactively to allowances payable from 1 April 2025, and 1 April 2026 added four bands above 65km along with the parking addition. Figures learnt before those dates are wrong, and wrong in a direction that under-states the exempt amount. Call with no arguments to read the current table and both revisions.

Parameters4

amount	number	optional	The commuting allowance actually paid, yen per month. Omit to get the whole table.
distance_km	number	optional	One-way distance for a commute by car or bicycle. Under 2km nothing is exempt.
fare	number	optional	Reasonable fare or toll paid alongside a vehicle commute.
parking	number	optional	Monthly parking cost the employee bears. Added to the distance band, up to 5,000. Needs distance_km.

Raw schema

{
  "type": "object",
  "properties": {
    "amount": {
      "description": "The commuting allowance actually paid, yen per month. Omit to get the whole table.",
      "type": "number"
    },
    "distance_km": {
      "description": "One-way distance for a commute by car or bicycle. Under 2km nothing is exempt.",
      "type": "number"
    },
    "fare": {
      "description": "Reasonable fare or toll paid alongside a vehicle commute.",
      "type": "number"
    },
    "parking": {
      "description": "Monthly parking cost the employee bears. Added to the distance band, up to 5,000. Needs distance_km.",
      "type": "number"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

check_data_freshness

Japanese statutory figures change on fixed dates — insurance rates each March, employment insurance each April, minimum wage each October — and a stale table produces numbers that look plausible and are wrong. This reports what every dataset currently covers and when its next revision is due. Worth calling before relying on a figure for a filing, and whenever a result is being checked against a date near one of those boundaries.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

README.md26 KBView on GitHub

jp-payroll-mcp

日本の給与計算・社会保険・労務を、表を引くのではなく計算して返すAPIとMCPサーバーです。 47都道府県の保険料率、源泉所得税、標準報酬月額の決定と改定、休業中の保険料免除、割増賃金、年次有給休暇、最低賃金、営業日計算、令和8年分の年末調整、住民税の見込み額まで。答えには根拠の条文または通知が付きます。

公表されている料額表・税額表と1セルずつ突き合わせ、変更のたびに 4,689件 の検証を実行します。

使いかたは2通り

MCPサーバー — AIアシスタントに日本語で聞く。30ツール、無料、APIキー不要。 URL を貼るだけ(remote MCP)か、npx で入れるか:

bash

claude mcp add --transport http jp-payroll https://japan-payroll-api.tsumugi.workers.dev/mcp

bash

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

Claude.ai のカスタムコネクタ、ChatGPT、Cursor には https://japan-payroll-api.tsumugi.workers.dev/mcp を貼ります。

HTTP API — ソフトウェアに組み込む。45エンドポイント、OpenAPI 3.0、一括処理:

bash

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

MCPサーバーはAPIの薄い層なので、どちらも同じ答えを返します。人が聞くのか、プログラムが聞くのかの違いです。

なぜ要るのか

自前で書くと、もっともらしく見えて間違っている数字が出ます。3月31日退職と3月30日退職では 1か月分の社会保険料が動きます(東京・40歳・月給30万円で労使合計95,130円)。4月1日生まれの人は 3月31日に40歳になるので介護保険料が1か月早く始まります。随時改定の「2等級以上」は健康保険法に書いておらず、昭和36年保発第4号にあります。

解説記事: 日本の給与計算・社会保険をAPIとMCPにしました
MCPサーバーの詳細: mcp/README.md
大量処理の有料プラン: RapidAPI

以下は英語の詳細仕様です。

Japanese payroll, social insurance and labour law, computed rather than looked up — premiums for all 47 prefectures, withholding tax, standard remuneration decisions and revisions, leave exemptions, minimum wage — with the statute or ministerial notice each answer rests on.

Verified against the published tables cell by cell: 4,689 assertions on every change.

Two ways in

As an MCP server, for asking questions through an AI assistant. 30 tools, free, no key. Remote (paste a URL) or local (npx):

bash

claude mcp add --transport http jp-payroll https://japan-payroll-api.tsumugi.workers.dev/mcp

bash

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

For Claude.ai custom connectors, ChatGPT and Cursor, the URL is https://japan-payroll-api.tsumugi.workers.dev/mcp.

As an HTTP API, for building it into software. 45 endpoints, OpenAPI 3.0, batch:

bash

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

The MCP server is a thin layer over the API, so both give the same answers. Which you want depends on whether a person or a program is asking.

MCP server source and its own README: mcp/ · English
Live API: https://japan-payroll-api.tsumugi.workers.dev
OpenAPI spec: /openapi.json

Japanese statutory MCP servers mostly retrieve — they hand you the text of a law and leave the reasoning to you. This one computes, and returns the provision it relied on. They fit together rather than compete:

	"What does the law say?"	"So what do I pay?"
`labor-law-mcp`	45 labour and social insurance laws, MHLW and JAISH notices	—
`tax-law-mcp`	24 tax laws, 17 NTA circulars, tribunal decisions	—
`hourei-mcp-server`	Any Japanese law, via e-Gov	—
jp-payroll-mcp	The 28 provisions it cites, in full	Premiums, withholding tax, grade revisions, exemptions

If you already run one of those, add this alongside it. An assistant with both picks the right one per question.

Why this exists

No consolidated API exists. Developers assemble this from 協会けんぽ, 厚生労働省 and each prefectural labour bureau separately.
The rules are fiddly. Premiums are computed on the standard monthly remuneration (a 50-grade step function), not on actual salary — except employment insurance, which uses actual salary. Pension caps at grade 32. Long-term care applies only to ages 40–64. The employee share rounds half down (≤ 0.50 yen truncates). Getting one of these wrong produces numbers that look plausible and are wrong.

MCP server

Source in mcp/, with its own README (日本語) · English. Test it with npm run mcp:test — it drives a real stdio transport with the real MCP client, because a tool with a broken handler still lists perfectly and only fails when something calls it.

The MCP server is free and always will be. It is a distribution channel rather than a revenue one: npm pays nothing and MCP has no billing of its own. That is deliberate — the problem was never billing, which RapidAPI already handles, but discovery, and MCP is where the traffic for Japanese statutory data measurably is.

Endpoints

Endpoint	Description
`GET /`	API info and endpoint list
Payroll and insurance
`GET /v1/prefectures`	All 47 prefectures with JIS codes
`GET /v1/insurance-rates?prefecture=Tokyo`	Health, long-term care, pension, child-support rates
`GET /v1/standard-remuneration?remuneration=350000`	Grade lookup for a monthly amount
`GET /v1/standard-remuneration/table`	Full 50-grade table
`GET /v1/employment-insurance?business_type=general`	Employment insurance rates
`GET /v1/payroll?prefecture=Tokyo&monthly_salary=350000&age=40`	Full deduction breakdown
Minimum wage
`GET /v1/minimum-wage?prefecture=Tokyo&date=2020-01-01`	Rate in effect on a date
`GET /v1/minimum-wage/history?prefecture=Tokyo`	Full history since FY2002
Calendar
`GET /v1/holidays?year=2026`	Public holidays (or `from=`/`to=` for a range)
`GET /v1/holidays/check?date=2026-01-01`	Holiday / weekend / business-day flags
`GET /v1/business-days?from=&to=`	Count business days in a range
`GET /v1/business-days/shift?date=&days=1`	Move N business days forward or back
Tax
`GET /v1/consumption-tax?date=&amount=&reduced=`	Rate in force, optionally applied to an amount
`GET /v1/consumption-tax/history`	Every rate change since 1989
Identifiers
`GET /v1/corporate-number/validate?number=8700110005901`	法人番号 check digit (Peppol ICD 0188)
`GET /v1/corporate-number/check-digit?base=700110005901`	Check digit for a 12-digit base number
`GET /v1/invoice-number/validate?number=T8700110005901`	Qualified invoice registration number
Withholding tax
`GET /v1/withholding-tax?taxable_amount=300000&dependants=2`	Monthly withholding income tax (月額表)
`GET /v1/withholding-tax/daily?taxable_amount=12000&column=hei`	Daily table (日額表), including the 丙 column
`GET /v1/withholding-tax/computer?taxable_amount=400000`	Same, by the formula method (電算機計算の特例)
Bonuses
`GET /v1/bonus-tax?bonus=500000&previous_month_pay=350000`	Withholding on a bonus (賞与の算出率表)
`GET /v1/bonus-insurance?prefecture=Tokyo&bonus=800000&age=40`	Social insurance on a bonus, with both caps
Standard remuneration decisions
`GET /v1/standard-remuneration/regular?months=350000:30,352000:31,349000:30`	定時決定 (算定基礎) from April–June
`GET /v1/standard-remuneration/revision?current_remuneration=&months=&fixed_pay_change=`	Is a 随時改定 (月額変更) due?
`GET /v1/standard-remuneration/leave-end?kind=childcare&current_remuneration=&months=`	Revision on returning from leave
`POST /v1/standard-remuneration/annual-average`	年間平均による保険者算定, for seasonal work
Year-end adjustment
`POST /v1/year-end-adjustment`	年末調整 (令和8年分): every box of the 源泉徴収簿 from ⑦ to ㉗, plus an "if filed" estimate for medical/donation/casualty deductions
Resident tax
`POST /v1/resident-tax`	住民税の見込み額 from last year's income and the municipality: income and per-capita levies, adjustment credit, ふるさと納税, exemptions, every prefecture's surtax
Eligibility and leave
`GET /v1/eligibility?month=2026-03&left_on=2026-03-30`	Is a premium due in a joining or leaving month?
`GET /v1/leave-exemption?kind=childcare&start=&end=`	Which months a maternity or childcare leave exempts
`GET /v1/age-milestones?birth_date=1986-04-01`	When 40, 65, 70 and 75 are reached, and what changes
Batch
`POST /v1/payroll/batch`	Up to 500 payslips in one call, with run totals
Statutes
`GET /v1/statute?ref=健康保険法第43条`	Full text of a provision this API cites
`GET /v1/statute/index`	Every provision available, with its law
`include=statute_text`	Add to any endpoint to attach the text of whatever it cited
Meta
`GET /v1/enums`	Every accepted enum value and error code
`GET /v1/data-freshness`	What each dataset covers and when it changes next

prefecture accepts an English name (Tokyo, case-insensitive), Japanese (東京 or 東京都), or a JIS code (13).

The one call that matters

Running payroll for one employee is a single request:

bash

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

code

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

Dataset	Coverage	Source
Social insurance rates	47 prefectures, FY2026 (令和8年度), effective 2026-03	協会けんぽ保険料額表
Standard remuneration table	50 health grades / 32 pension grades	same
Employment insurance	3 business types, FY2026, effective 2026-04-01	厚生労働省
Minimum wage	47 prefectures × 24 years (FY2002–FY2025)	厚生労働省地域別最低賃金
Public holidays	1,067 days, 1955–2027	内閣府国民の祝日について
Consumption tax	4 rate periods since 1989, with reduced rate	国税庁 No.6303
Corporate number check digit	algorithm, no dataset	国税庁チェックデジットの計算
Withholding tax (monthly)	231 brackets + 9 high-income anchors, 令和8年分	国税庁源泉徴収税額表
Withholding tax (formula)	4 statutory tables, 令和8年分以降	電算機計算の特例

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:

bash

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

Year-end adjustment covers 令和8年分 only, from the Tax Agency's booklet published 2026-08-31 (minimum employment income deduction 740,000 yen, basic deduction up to 1,040,000 yen, the new 特定親族特別控除, the under-23 life-insurance rule). Medical, donation and casualty-loss deductions are outside 年末調整 by law; pass them as tax_return to get a separate "if the employee files" estimate.
FY2026 minimum wage is not included yet. As of 2026-09-02, 46 of 47 prefectures had issued their 答申 (Okinawa pending); the earliest take effect on 2026-10-01. The API serves FY2025, which is the rate currently in force, and refuses dates on or after the first revision with out_of_coverage rather than returning last year's figure. It will be refreshed from the Ministry's list once all 47 are published.
Workers employed at two or more establishments (二以上事業所勤務) are not apportioned. Premiums are split in proportion to remuneration at each establishment, but there is no input for the other employer's figure; the API calculates as if for one establishment.
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 4,689 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 combinations (5 prefectures × 50 grades) — 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

bash

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

bash

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.

bash

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:

bash

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.

bash

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:

bash

npx wrangler tail --format json

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

json

{"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

When	What changes
March	協会けんぽ prefectural rates, effective with the March salary month
April	Employment insurance rates; tax tables
Late Aug – October	Minimum wage, issued prefecture by prefecture, effective from October
February	Cabinet Office publishes the following year's holidays

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.

bash

npm run rapidapi:prepare

That command, for every recipe:

validates the recipe,
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,
writes build/openapi/<slug>.openapi.json,
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.

Install

Tools (30)

calculate_paysliplist_workers_compensation_ratescalculate_bonuscalculate_withholding_taxjudge_monthly_revisiondecide_regular_remunerationjudge_leave_end_revisioncalculate_payroll_batch

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "jp-payroll-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "jp-payroll-mcp@0.4.5"
      ]
    }
  }
}

io.github.kishida-devil/jp-payroll-mcp — Model Context Protocol (MCP) Server

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

Topics

calculate_payslip

list_workers_compensation_rates

calculate_bonus

calculate_withholding_tax

judge_monthly_revision

decide_regular_remuneration

judge_leave_end_revision

calculate_payroll_batch

decide_regular_remuneration_batch

judge_annual_average

lookup_standard_remuneration

national_insurance

calculate_annual_cost

judge_annual_leave

judge_worker_type

check_insurance_eligibility

check_leave_exemption

get_age_milestones

calculate_year_end_adjustment

estimate_resident_tax

get_insurance_rates

get_minimum_wage

business_days

validate_invoice_numbers_batch

validate_corporate_number

consumption_tax

get_statute_text

calculate_overtime_pay

commuting_allowance_exemption

check_data_freshness

jp-payroll-mcp

使いかたは2通り

なぜ要るのか

Two ways in

Related tools

Why this exists

MCP server

Endpoints

The one call that matters

Before you integrate

Data

Why not the statute

Citations resolve to text

Known gaps

Verification

Develop / deploy

Maintenance

Verifying the paid path

The dates that matter

Publishing pipeline

Browser session

Operational safety

Licence and attribution

Install

Related servers