jp-payroll-mcp

日本工资、社会保险和劳动法，通过计算而非查询——覆盖全部47个都道府县的保险费、源泉所得税、标准报酬决定与修订、休假免除、最低工资——每个答案都注明所依据的法律或部级通知。

逐单元格对照发布表格验证：每次变更都经过 3,638 项断言。

两种接入方式

作为 MCP 服务器，用于通过 AI 助手提问。17 个工具，免费，无需密钥：

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

作为 HTTP API，用于将其集成到软件中。36 个端点，OpenAPI 3.0，支持批量：

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

MCP 服务器是 API 之上的薄层，因此两者给出的答案相同。选择哪个取决于提问的是人还是程序。

• MCP 服务器源代码及其自带的 README：mcp/ · 日本語

• 在线 API：https://japan-payroll-api.tsumugi.workers.dev

• OpenAPI 规范：/openapi.json

Related MCP server: taiwan-payroll

相关工具

日本的法定 MCP 服务器大多是检索型——它们把法律文本交给你，由你自己推理。而本工具是计算型，并返回所依据的条款。它们互补而非竞争：

如果你已经在运行其中之一，请将本工具并排添加。同时拥有两者的助手会根据每个问题选择正确的工具。

为什么存在

• 没有统一的 API。 开发者需要分别从 協会けんぽ、厚生労働省 以及各都道府县劳动局收集这些信息。

• 规则很繁琐。 保险费按标准月报酬（一个 50 档的阶梯函数）计算，而非实际工资——但雇佣保险除外，它使用实际工资。养老金在第 32 档封顶。长期护理只适用于 40–64 岁。员工负担部分四舍五入（≤ 0.50 日元则截断）。其中任何一项弄错，都会产生看似合理但错误的数字。

MCP 服务器

源代码位于 mcp/，带有自带的 README · 日本語。使用 npm run mcp:test 进行测试——它驱动真实的 stdio 传输并配合真实的 MCP 客户端，因为一个处理程序损坏的工具仍然能完美地列出，只有被调用时才会失败。

MCP 服务器是免费的，而且永远免费。它是一条分发渠道而非收入渠道：npm 不收取任何费用，MCP 本身也没有计费系统。这是有意为之——问题从来不是计费（RapidAPI 已经处理了），而是发现性，而 MCP 正是日本法定数据流量可测量的所在地。

端点

prefecture 接受英文名称（Tokyo，不区分大小写）、日文（東京 或 東京都）或 JIS 代码（13）。

一次关键调用

为一名员工运行工资计算只需一次请求：

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

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

中间那一行才是关键。所得税是按扣除社会保险后的工资征收的，而不是按总工资，手工推导正是这个端点存在所要避免的错误。响应中还带有已解析的等级、每项保费拆分后的员工与雇主份额，以及产生税额的税档——这样算术结果可以被审计，而不是被盲目信任。

住民税由地方政府评估并通知雇主；没有 API 能计算它。传入 resident_tax= 后，它将从净工资中扣除。

传入 income_tax=false 则只计算社会保险。

集成之前

• GET /v1/enums 列出所有可接受的值——business_type、column、calendar——以及所有错误码，这样它们可以在构建时读取，而不是从 400 响应中才发现。

• 错误带有稳定的 code。invalid_request 和 missing_parameter 表示需要修正调用；out_of_coverage 表示输入有效但超出了已发布的范围，这需要不同的分支处理。不要依赖英文描述文本——它会变化。

• GET /v1/data-freshness 告诉你每个数据集的最新程度。

数据

所有数字都是从官方电子表格中以程序化方式提取的——不是手工抄录的。提取器见 scripts/。

为什么不直接用法律条文

所得税数字来自国税厅发布的表格，而不是通过 e-Gov 法律 API 获取的所得税法，因为法定版本省略了 2.1% 的复兴特别所得税。在 105,000–107,000 日元区间，乙栏在別表第二中是 3,700 日元，而实际中是 3,800 日元；低于 105,000 日元时是 3% 而不是 3.063%。法律条文不是工资计算的正确来源。

超过 740,000 日元后，表格不再是表格：它变成了带边际税率的锚点。这些锚点并不共线——每个都内嵌了舍入——因此保留已发布的锚点值而不是重新计算。乙栏只有两个锚点（740,000 和 1,710,000），而甲栏有九个，从甲栏锚点测量乙栏的超出部分会静默地少收。这在这里曾是一个真实的 bug，是通过逐单元格比较发现的。

引用解析为文本

只提一个法律名称然后让读者自己去找，只算半个答案。此 API 引用的每一条规定都附带在内，因此 健康保険法第43条 可以在同一次往返中转换为实际条文文字：

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

实际中引用有多种写法，全部都能解析——健保法43条、厚年法81条の2、徴収法11条、缺少"第"字、段落级引用、全角数字。e-Gov 的缩写不是实务人员使用的写法（e-Gov 称之为厚生年金法；大家都写厚年法），因此两种都接受。

条文文本在构建时从 e-Gov 法令 API 获取，而不是在请求时获取：如果每次请求都调用 e-Gov，那么他们的服务宕机时这个 API 也会跟着宕机。

scripts/extract-statutes.py 保存着唯一一份条文清单，测试套件会检查代码发出的每个引用都能解析——添加了一个没有对应条文的引用会导致构建失败，而不是静默地返回空结果。

已知缺口

• 年末调整表未包含。 令和8年分的「給与所得控除後の給与等の金額の表」截至 2026-08 尚未发布；国税厅大约在 9 月发布。令和8年度税制改正还将最低工资所得扣除提高到 740,000 日元，自 2026-12-01 起生效，因此该表也会变化。

• 令和8年度最低工资未包含。 截至 2026-08，各都道府县仍在陆续发布修订，自 2026 年 10 月起生效。API 提供的是令和7年度数据，即当前生效的费率。一旦全部 47 个都道府县发布完毕，必须刷新此数据。

• 雇用保险历史数据仅限令和8年度。 更早的年份未经一手来源验证，因此省略而不是猜测。

• 住民税不在范围内。 它取决于上一年度的收入和所在地方政府，且由地方政府征收而不是由雇主计算，因此 /v1/payroll 只扣除你传入的数字，从不自行推导。

• 判定端点只决定是否应申报；它们不是申报本身。 有几条规则取决于 API 无法看到的事实——季节性波动是否属于「業務の性質上例年発生することが見込まれる」、某项津贴是否为実費弁償、员工是否同意。这些是声明的输入，会在响应中原样回显，而且保险者在保険者算定下仍可能得出不同结论。

• 并非所有标准报酬路径都覆盖。 資格取得時決定返回决定的有效期，但不计算初始報酬月額（健保法42条1項有四种方法，其中三种需要关于其他员工的数字）。二以上事業所勤務——将多个雇主的报酬加总并在他们之间分摊保费——完全没有实现。固定工资在三个月窗口内两次变动时的重新锚定也没有实现。

• 一些实务要点无法溯源到一手文件，在响应中列为 guidance.fixed_pay.unverified 而不是直接断言：家族手当是否算作固定工资、带薪休假如何计入支払基礎日数、以及年俸制如何处理。二手来源对这三项意见一致；各部委似乎没有书面说明。

验证

test/verify.mjs 对运行中的服务器执行 3,638 条断言。其核心是将 API 计算的保费与官方協会けんぽ工作簿中印制的金额进行比较，覆盖 250 个都道府县 × 等级组合——即已发布的半额数字，而不是公式的重新实现。它还检查：

• 等级边界的连续性，以及边界日元值属于上一等级

• 厚生年金在第 1 级和第 32 级的截断

• 介护保险费在 40 岁开启、65 岁关闭

• 雇用保险按实际工资征收，而其他保费使用等级

• 时点最低工资（包括生效日期的前一天）

• 四种输入形式下的都道府县解析

• 全部 47 个都道府县返回有效的工资响应

• 工作日天数与独立计算的参考值对比

• 2026-09-22 国民の休日（仅因夹在两个其他假日之间而成为假日）

• 一次性皇室假日：大喪の礼、即位礼正殿の儀、結婚の儀

• 法人番号校验位与 NTA PDF 中的算例对比，以及同一基数的其他校验位全部被拒绝

• 源泉所得税表的每个已发布单元格——231 个税档 × 8 个甲栏加上乙栏，共 2,079 个数字，与国税厅自己的工作簿对比

• 通过发票校验位不被归因于法人：个人事业主也满足同样的规则，因此不能从号码推断持有者

• 日本年金機構发布的全部八个单等级随時改定案例——四个健康、四个厚生年金——每个都落在表格指定的标准报酬上，同时覆盖实际等级和实现使用的扩展刻度

• 健康和厚生年金独立判定：超过厚生年金上限的加薪会移动六个健康等级，而厚生年金等级完全不动

• 15 天定時決定回退仅对短時間就労者触发，不对其他人触发，且在任何时候的随時改定中都不触发

• 每个封闭值集合都出现在 /v1/enums 中，因此新枚举不可能在不触及集成者生成类型的端点的情况下发布

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

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

开发 / 部署

npm install
npx wrangler dev
npx wrangler deploy

数据嵌入在包中（约 40 KB gzip 压缩），因此没有数据库、没有 KV、没有冷启动。

响应带有 Cache-Control: public, max-age=3600, stale-while-revalidate=86400。一小时而不是一天，因为费率在已知日期变化，修正应在当天到达调用者；stale-while-revalidate 在后台刷新时保持响应即时。注意，workers.dev 响应不会在 Cloudflare 自己的边缘缓存——每个请求都会调用 Worker。如果值得做的话，自定义域名可以启用边缘缓存。

从日本对已部署的 Worker 进行测量：中位 65 ms，最大 83 ms 往返；gzip 将 50 级表从 6,841 字节压缩到 1,041 字节。

维护

法定数字在固定日期变化，错过修订的 API 会继续应答——用已经不再真实的数字。两种机制防止这种情况。

API 报告自身的过期程度。 GET /v1/data-freshness 说明每个数据集覆盖什么以及下次何时变更，主要数据响应带有 freshness 标记。即使我们的监控失败了，调用者也能看到过期的数字。

每周任务监视来源。

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

它检查两个独立的事项，因为单独任何一个都会留下缺口：源文件的哈希和 Last-Modified（捕捉静默重新发布），以及日历（捕捉部委在新 URL 发布修订而旧 URL 保持不变的情况）。

告警携带该数据集的确切命令，而不是指回这里。告警在数月后被阅读，通常是由一个已经忘记此仓库布局的人。

在需要之前排练提取器。 最低工资提取器带有 --check，它运行完整提取并与当前发布的数据进行比较，而不是写入任何内容：

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

它应该显示输出匹配。如果财政年度未变但输出不匹配，说明提取器和已发布数据已经偏离——这在 8 月知道比在新数字落地当天发现要好得多，那时人们倾向于直接发布脚本产生的任何内容。

注册为每周运行：

powershell -ExecutionPolicy Bypass -File scripts
egister_watch_task.ps1

验证付费路径

测试套件无法检查 RapidAPI 的付费计划是否获得完整大小的批次：这需要 RapidAPI 签发的代理密钥，而存在于测试中的密钥就不是密钥。它检查了与收入相关的那一半——即没有密钥的调用者不能通过设置请求头来声称付费计划。

在权益发生任何变更后，从日志中确认另一半：

npx wrangler tail --format json

从 RapidAPI 试验场调用任一端点，查看请求行。它应携带订阅名称：

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

plan 存在表示代理密钥匹配。rapidapi 请求上的 plan: null 表示不匹配——这意味着每个付费客户在付费的同时却被按免费层级的限额提供服务。这种失败从外部看是无声的，因此值得刻意检查，而不是等待投诉。

重要的日期

刷新任何数据集后，更新 src/data/freshness.json 并运行 npm run rapidapi:prepare，以便重新验证实时 API 并重新生成 OpenAPI 规范。

发布流水线

每个 API 都是 recipes/<slug>/recipe.py 下的一个配方——端点只在那里声明一次，OpenAPI 规范和 RapidAPI 上架文案都由它生成。

npm run rapidapi:prepare

该命令对每个配方执行以下操作：

1. 验证配方，

2. 调用实时 API 上每个已声明的端点，要求返回 200 且 JSON 可解析——对于带必需参数的端点，则要求在省略参数时返回 400。这正是捕获 recipe.py 与 src/index.ts 之间漂移的手段，

3. 将 build/openapi/<slug>.openapi.json 写入文件，

4. 发送一条 Discord 通知，其中包含列表 URL、规范路径以及要粘贴的确切值。

上架本身是手动的。位于 https://rapidapi.com/provider/<id>/new 的 Add-API 表单受 reCAPTCHA v3 保护，因此最终提交由人工完成——三个字段，选择 "Specify using: OpenAPI"，上传生成的规范。每个 API 大约需要两分钟，不会成为每周一到两个的发布节奏的瓶颈。

在 .env 中设置 DISCORD_WEBHOOK_URL（参见 .env.example），通知才能真正送达；否则消息只会打印到控制台。

浏览器会话

npm run rapidapi:login 会打开一个真实的 Chrome 窗口供你手动登录——脚本永远看不到密码。会话持久保存在 rapidapi_profile/（已被 git 忽略）。当会话过期时重新运行它。

运维安全

• state/pipeline.halt.json 会暂停一切，直到人工将其移除。当会话挂掉时调用 set_halt()；成功重新登录时调用 clear_halt()。

• pipeline/rapidapi/config.py 中的 MAX_PUBLISH_PER_DAY / MIN_SECONDS_BETWEEN_PUBLISH 让发布节奏保持人工可承受的速度。

许可证与署名

底层数据是日本政府开放数据，依据 公共データ利用規約(第1.0版)，该规约允许商业使用和署名再分发。每个响应都包含一个 attribution 块，注明来源。

本服务未获得任何日本政府机构的认可。 在依赖它进行法定申报之前，请对照官方来源核实。