gajian-mcp

🤔 Why

PPh 21 changed in 2024: monthly withholding now uses TER (tarif efektif rata-rata) tables from PP 58/2023, December settles the year with Pasal 17, and BPJS has its own rates and wage caps that move by date. LLMs and many online calculators get this wrong:

Related MCP server: payroll-normalizer-mcp

✨ What you get

A payslip, explained

payslip() for gaji pokok Rp10.000.000, status K/1, June 2025, office work (JKK class sangat rendah):

🚀 Use it

1. Library (Node >= 22, ESM, zero dependencies)

npm i gajian

Monthly payslip (January-November):

import { payslip } from 'gajian';

const slip = payslip({
  components: [{ label: 'Gaji pokok', amount: 10_000_000, fixed: true }],
  status: 'K/1',
  period: '2025-06',
  jkkClass: 'sangatRendah',
});
slip.gross;      // 10454000  (salary + employer JKK 24000 + JKM 30000 + BPJS Kesehatan 400000)
slip.pph21.tax;  // 156810    (TER B 1,5%)
slip.takeHome;   // 9443190   (minus PPh 21, JHT 200000, JP 100000, Kesehatan 100000)
slip.breakdown;  // [{ label: 'Potongan PPh 21', amount: 156810, rule: 'PP 58/2023 Pasal 2 ayat (5); Lampiran ...' }, ...]

December reconciliation for the same employee over 2025:

import { pph21December } from 'gajian';

pph21December({
  annualGross: 125_448_000,       // 12 x 10.454.000
  annualEmployeeJhtJp: 3_600_000, // 12 x (200.000 + 100.000)
  status: 'K/1',
  year: 2025,
  taxWithheldJanNov: 1_724_910,   // 11 x 156.810
});
// { biayaJabatan: 6000000, netIncome: 115848000, ptkp: 63000000, pkp: 52848000,
//   annualTax: 2642400, taxWithheldJanNov: 1724910, decemberTax: 917490, overpaid: 0, breakdown: [...] }

2. MCP server

Claude Code:

claude mcp add gajian -- npx -y gajian-mcp

Claude Desktop, Cursor and other MCP clients:

{ "mcpServers": { "gajian": { "command": "npx", "args": ["-y", "gajian-mcp"] } } }

Tools: payslip, pph21_monthly, pph21_daily, pph21_december, bpjs_contributions, list_rules. Inputs match the library functions; bad input comes back as a tool error.

3. Agent Skill

Copy skills/gajian to ~/.claude/skills/ (or <project>/.claude/skills/). The skill tells the agent when to call gajian, what to ask before computing, and to never compute TER from memory.

📚 API

All money is integer rupiah. period is 'YYYY-MM'. status is 'TK/0'..'TK/3', 'K/0'..'K/3'. jkkClass is 'sangatRendah' | 'rendah' | 'sedang' | 'tinggi' | 'sangatTinggi'.

Rates are basis points (rateBp: 150 = 1,5%). Tax is rounded down to whole rupiah; each function's TSDoc states its rounding.

📜 Sources

Generated from the rule data in packages/gajian/src/rules/. primary = read from the regulation itself; secondary = no official primary document found.

Note on the JP wage cap: the 2024 and 2025 values are secondary, and no 2026 value is loaded yet, so 2026 periods use the 2025 cap. The 2016-2023 adjustments are also missing (those periods fall back to the 2015 cap). If you have the BPJS Ketenagakerjaan letter for your period, pass it as jpWageCap. list_rules (MCP) and rules (library) show what is loaded.

🎯 Scope

Covered: PPh 21 for pegawai tetap (TER bulanan January-November, December reconciliation), pegawai tidak tetap (TER harian / Pasal 17, or TER bulanan if paid monthly), PTKP, BPJS Ketenagakerjaan (JHT, JKK, JKM, JP) and BPJS Kesehatan for peserta penerima upah. Periods from 2024-01.

Not covered:

• Part-year employees in December (annualisation, biaya jabatan cap of Rp500.000 x months worked).

• Zakat / sumbangan keagamaan wajib through the employer; other pension (DPLK) unless added to annualEmployeeJhtJp.

• Higher rate for recipients without NPWP.

• Gross-up / tunjangan pajak (PPh 21 borne by the employer).

• Pensiunan and PNS rules, PPh 21 for non-pegawai.

• THR and pesangon as separate rules.

• UMK/UMP lookup (pass kesehatanFloor), holidays, NPWP/NIK validation.

• JP wage caps for 2016-2023 (pass jpWageCap).

• Storage of personal data: everything is pure functions.

🗺️ Roadmap

• UMK/UMP dataset, with the SK Gubernur number cited per row.

• Zakat via employer.

• Part-year annualisation in December.

• Gross-up (tunjangan pajak).

• Higher rate without NPWP.

• THR.

• Pesangon.

⚠️ Disclaimer

This is not tax advice. gajian follows the cited regulations as closely as its tests can check, but check results against the regulation (and your tax consultant) before you rely on them.

📄 License

MIT. Contributions: see CONTRIBUTING.md.

🇮🇩 Bahasa Indonesia

gajian menghitung PPh 21 (TER PP 58/2023, rekonsiliasi Desember dengan Pasal 17) dan iuran BPJS (JHT, JKK, JKM, JP, Kesehatan) sebagai library TypeScript, server MCP, dan Agent Skill. Setiap tarif dan batas upah punya tanggal berlaku dan rujukan pasal + halaman regulasinya, dan setiap hasil punya breakdown baris per baris dengan dasar hukumnya.

• Library: npm i gajian, lalu payslip(...) untuk slip Januari-November dan pph21December(...) untuk Desember (contoh di atas).

• MCP: claude mcp add gajian -- npx -y gajian-mcp.

• Agent Skill: salin folder skills/gajian ke ~/.claude/skills/.

Batas upah JP 2024 dan 2025 bersumber sekunder, dan nilai 2026 belum dimasukkan; isi jpWageCap kalau punya surat BPJS Ketenagakerjaan yang lebih baru. Belum mencakup THR, pesangon, UMK/UMP, karyawan yang masuk/keluar di tengah tahun, gross-up, dan tarif tanpa NPWP.

Bukan nasihat pajak. Cocokkan hasilnya dengan regulasi.