台灣勞健保勞退試算 MCP server

taiwan-payroll

開源的台灣勞健保勞退法定費用計算引擎。輸入薪資與身份，算出勞保（含就保）、健保、勞退、職災與二代健保補充保費的各方負擔——並涵蓋薪資所得扣繳、月中到職／離職破月、健保補充保費申報媒體檔，以及勞保老年給付試算。

示意：在支援 MCP 的 AI 助理（Claude / Cursor 等）中呼叫 taiwan-payroll

• 🧮 線上試算：（免安裝，瀏覽器直接算）
• 🔌 三種介面：TypeScript（npm）、Python（PyPI，純 stdlib）、MCP server（給 AI 助理呼叫）
• 📑 官方對證：級距表與費率逐級取自主管機關公告，計算結果對官方範例黃金向量逐位元驗證
• 🔁 跨語言一致：TS 與 Python 讀同一份 data/、跑同一套 testdata/，結果逐位元相同
• 📦 零執行期依賴：core 不帶任何 runtime 套件

定位是「計算引擎」而非「法遵保證」。 內建民國 113–115（2024–2026）年度官方參數。

安裝

npm install taiwan-payroll      # TypeScript / Node
pip install taiwan-payroll      # Python

快速上手

import { createPayrollEngine } from 'taiwan-payroll';

const engine = createPayrollEngine({ year: 2026 });
const r = engine.calculate({
  monthlySalary: 42000,
  identity: 'category1',
  dependents: 1,
  employmentInsurance: true,
  pensionSelfContribution: 0.06,
});

console.log(r.employee); // { labor: 1050, health: 1302, pensionSelf: 2520, total: 4872 }
console.log(r.employer.occupational); // 職災雇主負擔

二代健保補充保費與破月計算

// 補充保費（六類所得：bonus/parttime/professional/dividend/interest/rent）
engine.calculateSupplementary({ type: 'bonus', amount: 200000, monthlyInsuredSalary: 42000 });
// → { type: 'bonus', chargeable: 32000, rate: '0.0211', premium: 675 }

// 月中到職／離職（勞保/職保/勞退按日；健保採官方「月底歸屬」原則）
engine.calculateProrated({ monthlySalary: 29500, startDate: '2026-03-08' });
// → { ..., days: { insured: 23 }, healthCharged: true }

健保破月採「月底歸屬原則」：以月底所屬投保單位計收整月——到職當月計整月、離職當月不計。此為健保署實務規則（非按日、與 15 日分水嶺無關）。

申報媒體檔（健保補充保費）

由申報資料產生健保署「補充保險費明細申報檔」（CSV／Big5），涵蓋 6 類所得：獎金(62)、兼職薪資(63)、執行業務(65)、股利(66)、利息(67)、租金(68)。每個產生器皆以健保署官方範例逐位元驗證，TS 與 Python 結果一致。

import { generateSupplementaryBonusFiling } from 'taiwan-payroll';

const { filename, content } = generateSupplementaryBonusFiling({
  year: 2026,
  filingDate: '20260901', // 用於檔名
  unit: { taxId: '11111111', name: '甲公司', phone: '0227065866', email: 'a@b.tw', contactName: '王小明' },
  records: [
    { action: 'I', payDate: '20260615', payeeId: 'A123456789', payeeName: '李四',
      bonusAmount: 50000, insuredSalary: 31800, ytdBonusCumulative: 150000, unitCode: '123456789' },
  ],
});
// filename: 'DPR111111111150901001.csv'
// content : Unicode 字串；檔案實際為 Big5，存檔時請以 Big5 編碼寫出。

• 獎金/兼職/執行業務/利息/租金：逐列補充保費由引擎計算。股利(generateSupplementaryDividendFiling)因含股票股利／雇主扣除等情形，逐列保費由呼叫端提供（另附便利函式 calcDividendPremium）。
• 輸出為「資料檔」供以官方入口上傳。Big5 編碼：TS 由呼叫端編碼，Python 提供 tobig5bytes()（core 維持零依賴）。
• API 詳見文件站 /docs/api。

勞保老年給付試算

依勞保局官方公式試算三種老年給付（皆對官方數值/公式驗證、TS≡Python）：

import { calcOldAgePension, calcOldAgeLumpSum, calcOldAgeSinglePayment, getYearData } from 'taiwan-payroll';
const d = getYearData(2026);
calcOldAgePension(d, { avgInsuredSalary: 32000, years: 35, months: 6 });     // 月領年金（擇優兩式，可提前/延後）
calcOldAgeLumpSum(d, { avgInsuredSalary: 30000, years: 10 });                // 老年一次金
calcOldAgeSinglePayment(d, { avgInsuredSalary: 30000, preSixtyYears: 20 });  // 一次請領（舊制基數）

Shortened. The full README is on GitHub.