Content
# Taiwan Payroll
[](https://www.npmjs.com/package/taiwan-payroll)
[](https://pypi.org/project/taiwan-payroll/)
[](#license)
[](https://smithery.ai/servers/supra126/taiwan-payroll)
An open-source Taiwan payroll calculation engine.
<p align="center">
<img src="./assets/mcp-demo.gif" alt="In AI assistant, call taiwan-payroll MCP server to calculate payroll instantly" width="760">
<br><sub>Demo: Calling taiwan-payroll in MCP-enabled AI assistant (Claude / Cursor etc.)</sub>
</p>
<p align="center">
<img src="./assets/calc-result.svg" alt="Monthly salary NT$42,000, category 1: employee burden NT$4,872, employer burden NT$8,315, government subsidy NT$864 (NTD/month, 2026)" width="760">
</p>
- 🧮 **Online Calculator**: <https://taiwan-payroll.vercel.app> (no installation required, calculate directly in browser)
- 🔌 **Three Interfaces**: TypeScript (npm), Python (PyPI, pure stdlib), MCP server (for AI assistants)
- 📑 **Official Verification**: Rate tables and levels taken from official announcements, calculation results verified against official examples
- 🔁 **Cross-language Consistency**: TS and Python read the same `data/`, run the same `testdata/`, with identical results
- 📦 **Zero Runtime Dependencies**: core package does not rely on any runtime libraries
> **Positioned as a "calculation engine", not a "legal compliance guarantee".** Built-in parameters for 2024-2026.
## Installation
```bash
npm install taiwan-payroll # TypeScript / Node
pip install taiwan-payroll # Python
```
## Quick Start
```ts
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); // Occupational accident insurance employer burden
```
## Supplementary Health Insurance Premium and Prorated Calculation
```ts
// Supplementary premium (six types of income: bonus/part-time/professional/dividend/interest/rent)
engine.calculateSupplementary({ type: 'bonus', amount: 200000, monthlyInsuredSalary: 42000 });
// → { type: 'bonus', chargeable: 32000, rate: '0.0211', premium: 675 }
// Prorated calculation (labor/occupational insurance/pension by day; health insurance by official "end-of-month attribution" principle)
engine.calculateProrated({ monthlySalary: 29500, startDate: '2026-03-08' });
// → { ..., days: { insured: 23 }, healthCharged: true }
```
> **Health insurance prorated calculation uses "end-of-month attribution principle"**: The insurance premium is calculated based on the insured unit at the end of the month.
## Filing Media File (Health Insurance Supplementary Premium)
Generate a health insurance supplementary premium filing media file (CSV/Big5) covering six types of income.
```ts
import { generateSupplementaryBonusFiling } from 'taiwan-payroll';
const { filename, content } = generateSupplementaryBonusFiling({
year: 2026,
filingDate: '20260901',
unit: { taxId: '11111111', name: 'Company A', phone: '0227065866', email: 'a@b.tw', contactName: 'John Doe' },
records: [
{ action: 'I', payDate: '20260615', payeeId: 'A123456789', payeeName: 'Jane Doe',
bonusAmount: 50000, insuredSalary: 31800, ytdBonusCumulative: 150000, unitCode: '123456789' },
],
});
// filename: 'DPR111111111150901001.csv'
// content : Unicode string; actual file is Big5-encoded
```
## Old-age Pension Calculation
Calculate three types of old-age pensions.
```ts
import { calcOldAgePension, calcOldAgeLumpSum, calcOldAgeSinglePayment, getYearData } from 'taiwan-payroll';
const d = getYearData(2026);
calcOldAgePension(d, { avgInsuredSalary: 32000, years: 35, months: 6 }); // Monthly pension (optimal of two formulas, can be claimed early or delayed)
calcOldAgeLumpSum(d, { avgInsuredSalary: 30000, years: 10 }); // Old-age lump sum
calcOldAgeSinglePayment(d, { avgInsuredSalary: 30000, preSixtyYears: 20 }); // Single payment (old system)
```
## Architecture
- `data/{year}.json` — Single source of truth, annual regulatory parameters (rate tables), validated by JSON Schema.
- `testdata/` — Language-agnostic test vectors (official examples), basis for cross-language consistency.
## Other Languages and Interfaces
- **Python**: `pip install taiwan-payroll`, pure stdlib, API corresponds to TS version ([PyPI](https://pypi.org/project/taiwan-payroll/)).
- **MCP server**: Let AI assistants like Claude call the calculation directly. Remote endpoint `https://taiwan-payroll.simoko.workers.dev/mcp` (Streamable HTTP), or local `npx taiwan-payroll-mcp` (stdio, [npm](https://www.npmjs.com/package/taiwan-payroll-mcp)).
- **Online Calculator and Full API**: <https://taiwan-payroll.vercel.app>
## Data Sources (2026)
| Item | Authority | Document Number |
|---|---|---|
| Labor Insurance Salary Scale (11 levels, up to 45,800) | Ministry of Labor | Labor Insurance 2 Letter No. 1140091863 |
| Labor Retirement Contribution Scale (62 levels, up to 150,000) | Ministry of Labor | Labor Welfare 3 Letter No. 1140153598 |
| Occupational Accident Insurance Salary Scale (21 levels, up to 72,800) | Ministry of Labor | Occupational Accident Insurance Act §17 |
| Health Insurance Premium Scale (58 levels, up to 313,000) | Ministry of Health and Welfare | Health Insurance 2 Letter No. 1140153424 |
Rates: Labor Insurance 12.5% (including Employment Insurance 1%), Health Insurance 5.17%, Labor Retirement 6%, Occupational Accident Insurance 0.21%, Supplementary Health Insurance Premium 2.11%.
## Development
```bash
pnpm install
pnpm validate:data # Validate data schema, level continuity, and vector format
pnpm -r test # Run all test vectors
pnpm typecheck
```
## Disclaimer
This package is implemented based on public regulations and official announcements. Calculation results are for reference only, and actual payments should be based on the Labor Bureau and Health Insurance Bureau's notifications. This package does not constitute legal or accounting advice.
## License
MIT
