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

jp-payroll-mcp

这是一个用于计算日本工资、社会保险和劳动事务的 API 与 MCP 服务，而不是查阅表格后返回结果。 涵盖 47 个都道府县的保险费率、源泉所得税、标准报酬月额的确定与调整、休假期间的保险费免除、 加班工资、带薪年假、最低工资、工作日计算、令和 8 年年末调整，以及居民税预估金额。每个答案都附有依据的法条或通知。

我们逐格对照公开的金额表和税额表进行核验，每次变更都会运行 4,689 项验证。

两种使用方式

MCP 服务——用日语向 AI 助手提问。提供 30 个工具，免费，无需 API 密钥。 粘贴 URL（远程 MCP），或通过 npx 安装：

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

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 和批量处理：

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

以下是英文详细规格。

---

日本工资、社会保险和劳动法，采用计算而非查表的方式提供结果—— 涵盖所有 47 个都道府县的保险费、源泉所得税、标准报酬的确定与调整、休假期间免缴、最低工资；每个 答案都附有其依据的法令或部长通知。

逐格对照公开表格进行核验：每次变更都会运行 4,689 项断言。

两种使用方式

作为 MCP 服务，通过 AI 助手提问。提供 30 个工具，免费，无需密钥。 远程使用（粘贴 URL）或本地使用（npx）：

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

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

在 Claude.ai 自定义连接器、ChatGPT 和 Cursor 中，URL 为 https://japan-payroll-api.tsumugi.workers.dev/mcp。

作为 HTTP API，集成到软件中。提供 45 个端点、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/ · English
• 在线 API：https://japan-payroll-api.tsumugi.workers.dev
• OpenAPI 规范：/openapi.json

相关工具

日本的法令类 MCP 服务大多只负责检索——它们提供法律文本，把推理工作留给你。这个工具则负责计算， 并返回其所依据的条文。两者相辅相成，而非相互竞争：

	“法律规定是什么？”	“那么我该付多少？”
labor-law-mcp	45 部劳动与社会保险法律、厚生劳动省和日本安全卫生信息中心通知	—
tax-law-mcp	24 部税法、17 份国税厅通达、裁决案例	—
hourei-mcp-server	通过 e-Gov 查询任何日本法律	—
jp-payroll-mcp	完整列出其引用的 28 项条文	保险费、源泉所得税、等级调整、免缴

如果你已经在使用其中一种工具，可以再搭配使用这个工具。配备两者的助手会根据问题 选用合适的工具。

为什么开发这个项目

• **不存在统一的 API。**开发者需要分别从全国健康保险协会、厚生劳动省以及各都道府县劳动局收集数据。
• **规则繁琐。**保险费按标准报酬月额（共 50 个等级的阶梯函数）计算，而非按实际工资计算——就业保险则是例外， 按实际工资计算。养老金在第 32 级封顶。护理保险仅适用于 40 至 64 岁人群。 员工承担的部分按五舍六入取整（≤ 0.50 日元直接舍去）。任何一处出错， 得出的数字看似合理，实际却是错误的。

MCP 服务

源码位于 mcp/，其中附有独立的 README（日本語）· English。使用 npm run mcp:test 进行测试——该命令会通过真实的 stdio 传输与真实的 MCP 客户端进行交互，因为即使工具的处理程序已损坏，它仍能正常列出，只有在被调用时才会失败。

MCP 服务免费，并且将始终免费。它是一个分发渠道，而非营收渠道：npm 不会支付任何费用，MCP 也没有自己的计费功能。这是有意为之——问题从来不是计费，RapidAPI 已经解决了这个问题；真正的问题是发现，而对于日本法定数据而言，MCP 是有实测流量的渠道。

端点

端点	描述
GET /	API 信息和端点列表
工资与保险
GET /v1/prefectures	全部 47 个都道府县及 JIS 代码
GET /v1/insurance-rates?prefecture=Tokyo	健康保险、长期护理保险、养老金和育儿支援费率
GET /v1/standard-remuneration?remuneration=350000	查询月额对应的等级
GET /v1/standard-remuneration/table	完整的 50 级表
GET /v1/employment-insurance?business_type=general	雇用保险费率
GET /v1/payroll?prefecture=Tokyo&monthly_salary=350000&age=40	完整的扣款明细
最低工资
GET /v1/minimum-wage?prefecture=Tokyo&date=2020-01-01	某日期生效的费率
GET /v1/minimum-wage/history?prefecture=Tokyo	自 FY2002 起的完整历史记录
日历
GET /v1/holidays?year=2026	公共假日（或使用 from=/to= 指定范围）
GET /v1/holidays/check?date=2026-01-01	假日／周末／工作日标记
GET /v1/business-days?from=&to=	计算指定范围内的工作日数量
GET /v1/business-days/shift?date=&days=1	向前或向后移动 N 个工作日
税务
GET /v1/consumption-tax?date=&amount=&reduced=	生效税率，可选应用于指定金额
GET /v1/consumption-tax/history	自 1989 年起的所有税率变更
标识符
GET /v1/corporate-number/validate?number=8700110005901	法人番号校验位（Peppol ICD 0188）
GET /v1/corporate-number/check-digit?base=700110005901	12 位基础号码的校验位
GET /v1/invoice-number/validate?number=T8700110005901	合格发票登记号码
预扣税
GET /v1/withholding-tax?taxable_amount=300000&dependants=2	月度预扣所得税（月額表）
GET /v1/withholding-tax/daily?taxable_amount=12000&column=hei	日额表（日額表），包括丙栏
GET /v1/withholding-tax/computer?taxable_amount=400000	使用公式法计算的相同税额（電算機計算の特例）
奖金
GET /v1/bonus-tax?bonus=500000&previous_month_pay=350000	奖金预扣税（賞与の算出率表）
GET /v1/bonus-insurance?prefecture=Tokyo&bonus=800000&age=40	奖金的社会保险费，含两项上限
标准报酬决定
GET /v1/standard-remuneration/regular?months=350000:30,352000:31,349000:30	根据 4 月至 6 月的收入进行定时决定（算定基礎）
GET /v1/standard-remuneration/revision?current_remuneration=&months=&fixed_pay_change=	是否需要进行随时改定（月額変更）？
GET /v1/standard-remuneration/leave-end?kind=childcare&current_remuneration=&months=	休假结束返岗时的修订
POST /v1/standard-remuneration/annual-average	通过年度平均进行保险人核定（年間平均による保険者算定），适用于季节性工作
年末调整
POST /v1/year-end-adjustment	年末调整（令和8年分）：源泉徴収簿中从 ⑦ 到 ㉗ 的所有项目，另附一份“如果申报”的医疗费／捐赠／灾害损失扣除估算
居民税
POST /v1/resident-tax	根据上一年度收入和所在市町村估算居民税（住民税の見込み額）：所得税额和人均税额、调整抵免、ふるさと納税、减免，以及各都道府县的附加税
资格与休假
GET /v1/eligibility?month=2026-03&left_on=2026-03-30	入职或离职当月是否需要缴纳保险费？
GET /v1/leave-exemption?kind=childcare&start=&end=	产假或育儿假可免缴保费的月份
GET /v1/age-milestones?birth_date=1986-04-01	何时达到 40、65、70 和 75 岁，以及相应变化
批量
POST /v1/payroll/batch	一次调用最多处理 500 份工资单，并提供总计
法规
GET /v1/statute?ref=健康保険法第43条	此 API 引用的条文全文
GET /v1/statute/index	所有可用条文及其所属法律
include=statute_text	添加到任意端点，即可附上其引用的条文文本
元数据
GET /v1/enums	所有可接受的枚举值和错误代码
GET /v1/data-freshness	各数据集的覆盖范围及下次更新日期
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 会告知各数据集的最新程度。

数据

数据集	覆盖范围	来源
社会保险费率	47 个都道府县，FY2026（令和 8 年度），自 2026-03 起生效	協会けんぽ 保険料額表
标准报酬表	50 个健康保险等级 / 32 个养老金等级	同上
雇用保险	3 种业务类型，FY2026，自 2026-04-01 起生效	厚生労働省
最低工资	47 个都道府县 × 24 年（FY2002–FY2025）	厚生労働省 地域別最低賃金
公共假日	1,067 天，1955–2027 年	内閣府 国民の祝日について
消费税	自 1989 年起的 4 个税率期间，含减轻税率	国税庁 No.6303
法人编号校验位	算法，无数据集	国税庁 チェックデジットの計算
预扣所得税（月额）	231 个档位 + 9 个高收入锚点，令和 8 年份	国税庁 源泉徴収税額表
预扣所得税（公式）	4 张法定税表，适用于令和 8 年份及以后	電算機計算の特例

所有数值均通过程序从官方电子表格中提取，并非手工转录。提取工具见 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），甲栏则有九个；根据甲栏锚点测算乙栏超出部分会造成隐性少扣税款。这是此处曾出现的真实错误，通过逐单元格对比发现。

引用可解析为文本

只写出法规名称，让读者自行查找，只算答了一半。本 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-31 发布的手册（最低工资收入扣除额为 740,000 日元，基础扣除额最高为 1,040,000 日元，新增 特定親族特別控除，以及未满 23 岁人群的生命保险规则）。依法，医疗、捐赠和灾害损失扣除不属于 年末調整；将其作为 tax_return 传入，即可获取单独的“如果员工提交申报”估算。

• **尚未纳入 FY2026 最低工资。**截至 2026-09-02，47 个都道府县中有 46 个已发布 答申（冲绳尚未发布）；最早的生效日期为 2026-10-01。API 提供的是 FY2025 数据，即当前适用的费率；对于首次调整日期当天或之后的日期，API 会返回 out_of_coverage，而不是给出上一年的数值。待全部 47 个都道府县公布后，API 将根据厚生劳动省的清单更新。

• **未对在两家或以上单位工作的员工（二以上事業所勤務）进行分摊。**保费按各单位的报酬比例分摊，但没有输入项可提供其他雇主的金额；API 按仅在一家单位工作的情况计算。

• **雇用保险历史数据仅涵盖 FY2026。**由于早期年份未经一手来源核实，因此不予提供，而不是猜测。

• **居民税不在范围内。**居民税取决于上一年的收入和所在市町村，并由市町村征收，而非雇主计算，因此 /v1/payroll 会扣除你传入的金额，绝不会自行推算。

• **判定端点用于判断是否需要申报，并非代为申报。**有几项规则取决于 API 无法获知的事实——例如季节性波动是否「業務の性質上例年発生することが見込まれる」、某项津贴是否属于実費弁償、员工是否已同意。这些都作为声明输入，并在响应中原样返回；保险机构仍可根据 保険者算定得出不同结论。

• **并未涵盖所有标准报酬的确定方式。**資格取得時決定会返回该决定持续有效的时间，但不会计算初始 報酬月額（健保法42条1項有四种方法，其中三种需要其他员工的数据）。二以上事業所勤務——即汇总多个雇主的报酬并在其间分摊保费——完全未实现。固定工资在三个月窗口内变动两次时发生的重新定基，也未实现。

• 少数实务事项无法从一手文件中找到依据，因此在响应中标记为 guidance.fixed_pay.unverified，而非作为确定结论：家族津贴是否计入固定工资、带薪休假是否计入 支払基礎日数，以及 年俸制 的处理方式。二手来源对这三点的说法一致，但相关部门似乎没有书面说明。

验证

test/verify.mjs 会对运行中的服务运行 4,689 项断言。核心测试是将 API 计算出的保费与官方協会けんぽ工作簿中列出的金额进行比较，覆盖 250 种组合（5 个都道府县 × 50 个等级）——采用公布的个人负担金额，而非重新实现公式。还会检查：

• 等级边界是否连续，以及边界日元金额是否属于较高等级
• 养老金在等级 1 和 32 时是否正确封顶
• 长期护理保险是否在 40 岁时开始缴纳，并在 65 岁时停止
• 就业保险是否按实际工资计费，而其他保费是否按等级计费
• 指定时间点的最低工资（包括生效日期的前一天）
• 是否支持通过全部四种输入形式解析都道府县
• 全部 47 个都道府县是否都能返回有效的工资结算响应
• 工作日计数是否与独立计算的参考值一致
• 2026-09-22 的国民の休日（仅因位于另外两个节日之间才成为假日）
• 一次性皇室假日：大喪の礼、即位礼正殿の儀、結婚の儀
• 法人编号校验位是否与 NTA PDF 中的计算示例一致，以及是否会拒绝同一主体的所有其他校验位
• 源泉扣缴税额表公布的每个单元格——231 个区间 × 8 个甲栏，加上乙栏，共 2,079 个数值，并与国税厅自己的工作簿进行比较
• 通过发票校验位检查并不意味着该号码属于法人：个人经营者也满足相同规则，因此无法根据号码推断持有人身份
• 日本年金機構公布的全部 8 种单等级随時改定案例——健康保险 4 种、养老金 4 种——每种都应得出表中指定的标准报酬，并分别在实际等级和实现所用的扩展等级范围内验证
• 健康保险和养老金是否独立判定：超过养老金上限的加薪会使健康保险等级上升 6 级，而养老金等级完全不变
• 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

数据嵌入在程序包中（gzip 压缩后约 40 KB），因此无需数据库、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 上发布修订版，却不改动旧版本）。

警报会附上该数据集的确切命令，而不是让人回到这里查找。几个月后看到警报的人，通常已经忘了这个仓库的布局。

提前演练提取器。 最低工资提取器支持 --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 表示密钥不匹配——每位付费客户都会受到免费套餐的限制，却仍被收费。这种故障在外部是无声的，因此值得主动检查，而不是等到有人投诉。

重要日期

时间	变更内容
March	協会けんぽ 各都道府县的费率，于 3 月工资月份生效
April	劳动保险费率；税额表
Late Aug – October	最低工资，按都道府县陆续发布，自 10 月起生效
February	内阁府发布次年的节假日安排

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

发布流水线

每个 API 都是 recipes/<slug>/recipe.py 下的一份配方——端点只需在此声明一次，OpenAPI 规范和 RapidAPI 列表文本都会据此生成。

npm run rapidapi:prepare

对于每份配方，该命令都会：

1. 验证配方，
2. 调用线上 API 上声明的每个端点，并要求返回可解析的 JSON 和 200 状态码——对于有必需参数的端点，还要求省略参数时返回 400。此步骤可捕捉 recipe.py 与 src/index.ts 之间的偏差，
3. 写入 build/openapi/<slug>.openapi.json，
4. 发送 Discord 通知，其中包含列表 URL、规范路径以及需要粘贴的确切值。

列表需要手动创建。Add-API 表单位于 https://rapidapi.com/provider/<id>/new，并受 reCAPTCHA v3 保护，因此最终提交由人工完成——填写三个字段，选择“Specify using: OpenAPI”，然后上传生成的规范。每个 API 大约需要两分钟，不会拖慢每周发布一到两个 API 的节奏。

在 .env 中设置 DISCORD_WEBHOOK_URL（参见 .env.example），通知才能实际送达；未设置时，消息只会打印到控制台。

浏览器会话

npm run rapidapi:login 会打开一个真实的 Chrome 窗口，供你手动登录——脚本不会获取密码。会话会保存在 rapidapi_profile/ 中（已加入 gitignore）。会话过期后，请重新运行该命令。

操作安全

• state/pipeline.halt.json 会暂停所有操作，直到有人将其移除。会话失效时会调用 set_halt()；重新登录成功后会调用 clear_halt()。
• pipeline/rapidapi/config.py 中的 MAX_PUBLISH_PER_DAY / MIN_SECONDS_BETWEEN_PUBLISH 用于控制发布频率，使其符合人工操作的节奏。

许可与署名

底层数据是日本政府的开放数据，遵循公共データ利用規約(第1.0版)，该协议允许商业使用和再分发，但须注明出处。每个响应都包含一个注明来源的 attribution 区块。

本服务未获得任何日本政府机构的认可。 在将其用于法定申报前，请先对照官方来源进行核实。