io.github.supra126/taiwan-payroll MCP Server

This MCP server provides Taiwan payroll calculations for labor insurance, national health insurance, labor pension, workplace injury coverage, and second-generation health insurance additional premiums. It includes payroll withholding, “破月” handling, and labor insurance old-age benefits. Source data comes from official regulator announcements, validated against official examples at a per-byte level.

🛠️ Key Features

台灣勞保、健保、勞退、職災試算
二代健保補充保費試算
薪資扣繳、破月處理
勞保老年給付

🚀 Use Cases

Validate Taiwan payroll components against official announcements
Compute withholding and related items for Taiwan salary processing

⚡ Developer Benefits

Deterministic, byte-level verified results vs official examples
Accessible via Model Context Protocol (MCP)
Structured for developer tooling (9 tools)

⚠️ Limitations

Depends on data from主管機關公告 and official examples for verification
Scope is Taiwan-specific insurance, pension, and related payroll calculations

taiwan-payroll

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

在 AI 助理中以自然語言詢問薪資，taiwan-payroll MCP server 呼叫 calculate_payroll 即時算出員工自付 4,872、雇主負擔 8,315
_{示意：在支援 MCP 的 AI 助理（Claude / Cursor 等）中呼叫 taiwan-payroll}

月薪 42,000 第一類計算結果：員工負擔 4,872、雇主負擔 8,315、政府補助 864（新台幣／月，民國115年度）

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

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

安裝

bash

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 提供 to_big5_bytes()（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 });  // 一次請領（舊制基數）

老年年金：擇優兩式（平均×年資×0.775%+3000 vs ×1.55%），提前/延後 claimOffsetMonths（±4%/年、上限 ±5 年（±20%））；附 averageHighestInsuredSalary、statutoryClaimAge。
老年一次金：年資每滿 1 年發 1 個月，逾 60 歲後年資最多 5 年。
一次請領：基數制（前 15 年每年 1 基數、超過部分每年 2 基數、前 60 上限 45、合併上限 50），平均採退保前 36 個月。
試算僅供參考，實際以勞保局核定為準。

架構

data/{year}.json — 單一事實來源，年度法規參數（級距表、費率），以 JSON Schema 驗證。
testdata/ — 語言無關的黃金測試向量（官方案例，含 source 出處），是跨語言行為一致性的根基。
packages/core — 零執行期依賴的 TypeScript 引擎。

其他語言與介面

Python：pip install taiwan-payroll，純 stdlib、API 對應 TS 版（PyPI）。
MCP server：讓 Claude 等 AI 助理直接呼叫試算。遠端免安裝端點 https://taiwan-payroll.simoko.workers.dev/mcp（Streamable HTTP），或本地 npx taiwan-payroll-mcp（stdio，npm）。
- 上架於官方 MCP Registry（io.github.supra126/taiwan-payroll）、Smithery（一鍵安裝）與 Glama。
線上計算機與完整 API：https://taiwan-payroll.vercel.app

資料來源（2026 / 民國115年）

項目	主管機關	文號
勞保投保薪資分級表（11級，上限45,800）	勞動部勞保局	勞動保2字第1140091863號令
勞退月提繳分級表（62級，上限150,000）	勞動部勞保局	勞動福3字第1140153598號令
職災投保薪資分級表（21級，上限72,800）	勞動部勞保局	職災保險法§17
健保投保金額分級表（58級，上限313,000）	衛福部健保署	衛部保字第1140153424號令

費率：勞保 12.5%（含就保 1%）、健保 5.17%、勞退雇主 6%、職災平均 0.21%、二代健保補充保費 2.11%。

目前內建民國 113／114／115（2024／2025／2026） 三個年度，各年度的分級表與文號見 data/{year}.json 的 sources；以 createPayrollEngine({ year }) 指定，可用年度由 getAvailableYears() 取得。

開發

bash

pnpm install
pnpm validate:data   # 驗證 data schema、級距連續性、向量格式
pnpm -r test         # 跑全部黃金測試向量
pnpm typecheck

免責聲明

本套件依公開法規與主管機關公告實作，計算結果僅供參考，實際應繳金額以勞保局、健保署核發之繳款單為準。本套件不構成法律或會計建議。

License

MIT

year	integer	optional	年度（西元，如 2026）。省略則使用最新可用年度；可先用 list_years 查可用年度。
monthlySalary	number	required	月薪資總額（經常性薪資），新臺幣元／月。
identity	string	optional	身份別（預設 category1）：category1=本國勞工或外籍配偶；migrantGeneral=一般移工（勞保僅普通事故 11.5%、無就保/勞退）；migrantDomestic=家事移工（僅健保＋職災，職災費率請以 occupationalRate 傳 0.0018）。不適用的險種回傳 0。
dependents	integer	optional	健保眷屬人數（計費上限 3 口），預設 0。
employmentInsurance	boolean	optional	是否參加就業保險（勞保費率 12.5% 或 11.5%），預設 true。一般移工/家事移工一律視為不參加。
pensionSelfContribution	number	optional	勞工自願提繳率，小數（0~0.06，如 0.06 表 6%），預設 0。
occupationalRate	number	optional	職災行業別費率，小數比例（如 0.0021 表 0.21%；家事移工 0.0018），範圍 [0, 0.02)。省略則用該年度平均費率。
partTime	boolean	optional	是否為部分工時：true 時未達基本工資者勞保/健保對到官方低級距（職保仍歸第 1 級）。預設 false。
rounding	string	optional	進位策略：round=四捨五入（預設）、ceil=無條件進位、aggregate-then-round=合計後分配（政府方吸收進位差）。

year	integer	optional	年度（西元，如 2026）。省略則使用最新可用年度；可先用 list_years 查可用年度。
type	string	required	所得類別：bonus=高額獎金、parttime=兼職薪資、professional=執行業務、dividend=股利、interest=利息、rent=租金。
amount	number	required	單次給付金額，新臺幣元。
monthlyInsuredSalary	number	optional	（僅 bonus 必填）給付當月之投保金額，新臺幣元／月；門檻為其 4 倍。
ytdBonus	number	optional	（僅 bonus）本次給付前、同雇主同年度已累計之獎金，預設 0。
rounding	string	optional	進位策略：round=四捨五入（預設）、ceil=無條件進位、aggregate-then-round=合計後分配（政府方吸收進位差）。

year	integer	optional	年度（西元，如 2026）。省略則使用最新可用年度；可先用 list_years 查可用年度。
monthlyPaidTotal	number	required	每月支付薪資所得總額 A，新臺幣元（含薪資、獎金、兼職、車馬費、承攬等）。
monthlyInsuredTotal	number	required	受僱者當月健保投保金額總額 B，新臺幣元（全體受僱者投保金額合計）。
rounding	string	optional	進位策略：round=四捨五入（預設）、ceil=無條件進位、aggregate-then-round=合計後分配（政府方吸收進位差）。

year	integer	optional	年度（西元，如 2026）。省略則使用最新可用年度；可先用 list_years 查可用年度。
type	string	required	扣繳類型：resident=居住者固定月薪(公式法)、residentBonus=居住者非每月給付(獎金)5%、nonResident=非居住者18%/6%。
monthlySalary	number	optional	月薪資，新臺幣元（resident／nonResident 用）。
dependents	integer	optional	配偶及受扶養親屬人數（僅 resident），預設 0。
amount	number	optional	該筆給付金額，新臺幣元（僅 residentBonus）。

year	integer	optional	年度（西元，如 2026）。省略則使用最新可用年度；可先用 list_years 查可用年度。
avgInsuredSalary	number	required	平均月投保薪資（最高 60 個月平均），新臺幣元。
years	integer	required	保險年資：年。
months	integer	optional	保險年資：月（0–11），預設 0。
claimOffsetMonths	integer	optional	提前(負)/延後(正)請領月數，相對法定請領年齡；每年 ±4%，上限 ±5 年（±20%）。預設 0。

台灣勞健保勞退試算

io.github.supra126/taiwan-payroll MCP Server

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

Topics

calculate_payroll

calculate_supplementary_premium

calculate_employer_supplementary_premium

calculate_income_tax_withholding

calculate_old_age_pension

calculate_old_age_lump_sum

calculate_old_age_single_payment

calculate_prorated

list_years