jp-payroll-mcp

# jp-payroll-mcp

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

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

## 使いかたは2通り

**MCPサーバー** — AIアシスタントに日本語で聞く。29ツール、無料、APIキー不要:

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

**HTTP API** — ソフトウェアに組み込む。44エンドポイント、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にしました](https://zenn.dev/kishida_devil/articles/9d5a645a105c0b)**
- MCPサーバーの詳細: **[mcp/README.md](mcp/README.md)**
- 大量処理の有料プラン: [RapidAPI](https://rapidapi.com/kishidadevil/api/japan-payroll-and-labor-constants)

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

---

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,661 assertions** on every change.

## Two ways in

**As an MCP server**, for asking questions through an AI assistant. 29 tools, free, no key:

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

**As an HTTP API**, for building it into software. 44 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/`](mcp/) · [English](mcp/README.en.md)
- Live API: `https://japan-payroll-api.tsumugi.workers.dev`
- OpenAPI spec: [`/openapi.json`](https://japan-payroll-api.tsumugi.workers.dev/openapi.json)

## Related tools

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`](https://www.npmjs.com/package/labor-law-mcp) | 45 labour and social insurance laws, MHLW and JAISH notices | — |
| [`tax-law-mcp`](https://www.npmjs.com/package/tax-law-mcp) | 24 tax laws, 17 NTA circulars, tribunal decisions | — |
| [`hourei-mcp-server`](https://www.npmjs.com/package/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/`](mcp/), with its own [README](mcp/README.md) (日本語) ·
[English](mcp/README.en.md). 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 ㉗ |
| **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"
```

```
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 | [協会けんぽ 保険料額表](https://www.kyoukaikenpo.or.jp/g7/cat330/sb3150/r08/r8ryougakuhyou3gatukara/) |
| Standard