Skip to main content
Glama
malaysia-payroll-mcp

malaysia-payroll-mcp

by davidyapcc
README.md
# malaysia-payroll-mcp

An MCP server that works out Malaysian statutory payroll deductions (EPF, SOCSO, SKBBK, EIS and MTD/PCB) for one employee's monthly salary, and cites the official rate table or rule behind every number.

**Status: pre-release.** EPF, SOCSO, SKBBK, EIS, MTD, net pay and the 35-case two-layer agent eval are in. Tagged releases are on GitHub, with changes listed in the [changelog](CHANGELOG.md); nothing is published to npm yet.

## Tools

| Tool | What it works out |
| --- | --- |
| `calculate_epf` | EPF employee and employer contributions, from the Third Schedule in effect |
| `calculate_socso_eis` | SOCSO, SKBBK (Lindung 24 Jam) and EIS contributions, from the PERKESO tables in effect |
| `calculate_mtd` | MTD (PCB) income tax deduction: LHDN's formula with the working shown for a tax resident, or the flat 30% for a non-resident (`taxResident: false`). Standard reliefs only (individual, spouse, children, EPF, plus a TP1 total) |
| `calculate_net_pay` | One month's payslip: every deduction above, net pay, and the employer's contributions and total cost. Runs the three calculators in one call and feeds the employee EPF into MTD |

Every result echoes the pay period it used (the current month in Malaysia if you don't pass one), and carries citations, an explanation rendered from them, and a disclaimer.

## Resources

Every rate table the tools read is also a read-only resource, as JSON with amounts in sen: `payroll://tables/{kind}/{effectiveFrom}`, where `kind` is `epf`, `socso`, `skbbk`, `eis` or `mtd` (LHDN's tax schedule). For example, `payroll://tables/epf/2025-10-01` is the EPF Third Schedule from 1 Oct 2025. `resources/list` shows them all, and the template completes both parts.

> Not tax advice, and not verified by KWSP, PERKESO or LHDN. Fixed monthly salaries only: overtime, commission, bonuses and arrears aren't supported, and neither is zakat.

## Install

Nothing is on npm yet, so build from source. You need Node 24 or later and pnpm.

```sh
git clone https://github.com/davidyapcc/malaysia-payroll-mcp.git
cd malaysia-payroll-mcp
pnpm install
pnpm build
```

## Usage

The server runs over stdio. Replace `/absolute/path/to` with where you cloned it.

**Claude Code:**

```sh
claude mcp add malaysia-payroll -- node /absolute/path/to/malaysia-payroll-mcp/dist/entry/stdio.js
```

**Claude Desktop**, in `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "malaysia-payroll": {
      "command": "node",
      "args": ["/absolute/path/to/malaysia-payroll-mcp/dist/entry/stdio.js"]
    }
  }
}
```

### Example

Calling `calculate_epf` with these arguments:

```json
{ "monthlySalary": 5000, "age": 34, "citizenship": "malaysian", "payPeriod": "2026-10" }
```

returns the following (amounts in RM, output from a real run):

```json
{
  "payPeriod": "2026-10",
  "monthlySalary": 5000,
  "part": "A",
  "employee": 550,
  "employer": 650,
  "total": 1200,
  "citations": [
    {
      "item": "EPF",
      "employee": 550,
      "employer": 650,
      "rule": "Part A applies to Malaysians, permanent residents and non-Malaysians registered before 1 Aug 1998, under 60. Up to RM20,000 the schedule's band amounts apply.",
      "tableRow": "Part A, RM4,980.01 to RM5,000.00",
      "source": {
        "title": "EPF Act 1991, Third Schedule (from 1 October 2025)",
        "url": "https://www.kwsp.gov.my/documents/d/guest/third_schedule_from_-1-october-2025",
        "retrieved": "2026-10-23"
      },
      "effectiveFrom": "2025-10-01"
    }
  ],
  "explanation": "EPF: employee RM550.00, employer RM650.00. Part A applies to Malaysians, permanent residents and non-Malaysians registered before 1 Aug 1998, under 60. Up to RM20,000 the schedule's band amounts apply. Table row: Part A, RM4,980.01 to RM5,000.00. Source: EPF Act 1991, Third Schedule (from 1 October 2025), in effect from 2025-10-01.",
  "disclaimer": "Not tax or legal advice, and not verified by KWSP, PERKESO or LHDN. Fixed monthly salaries only: overtime, commission, bonuses and arrears are not supported. Check results against the cited source."
}
```

## Docs

- [Architecture](docs/architecture.md): structure, stack and key decisions
- [Glossary](CONTEXT.md): the domain terms used in code and docs
- [Decision records](docs/adr/)
- [Official sources](docs/sources.md), with effective and retrieval dates
- [Golden test cases](docs/golden-cases.md), worked by hand from those sources
- [Rate tables](docs/data/) as CSV, the source of truth for every lookup

## Development

Needs Node 24 or later and pnpm (the version is pinned in `package.json`).

```sh
pnpm install
pnpm check          # generated tables, Biome lint and format check, tsc, Vitest
pnpm gen:tables     # regenerate src/tables/generated/ after editing docs/data/
pnpm test:coverage  # tests with v8 coverage
pnpm eval           # run 35-case two-layer agent eval (requires ANTHROPIC_API_KEY or OPENAI_API_KEY)
pnpm build          # compile to dist/
```

To change a rate, edit or add a CSV in `docs/data/` (with its entry in `docs/data/sources.json`), run `pnpm gen:tables` and commit both. Never edit `src/tables/generated/` by hand: CI rejects it ([ADR 0003](docs/adr/0003-csv-rate-tables-are-canonical.md)).

`pnpm eval` loads `.env` automatically if present and writes `evals/results/scorecard.json` and `evals/results/scorecard.md`:
- Set `ANTHROPIC_API_KEY` to run with Claude (`claude-haiku-4-5` by default).
- Or set `OPENAI_API_KEY` to run with OpenAI (`gpt-4o-mini` by default; override provider with `EVAL_PROVIDER=openai|anthropic` and models with `EVAL_AGENT_MODEL` / `EVAL_JUDGE_MODEL`).

## Licence

[MIT](LICENSE)

TDQS

A4.1/5.0

Scored across 4 tools

Disambiguation4/5

The three component calculators (MTD, EPF, SOCSO/EIS) are clearly distinct, while calculate_net_pay is an aggregate that intentionally overlaps with all of them. The descriptions explain this hierarchy, but an agent could still hesitate between using the full payslip tool and a specific component tool.

Naming Consistency5/5

All tools follow the same calculate_<subject> snake_case pattern. Acronyms and compound subjects like socso_eis are used consistently and remain readable.

Tool Count5/5

Four tools is well scoped for a focused Malaysian payroll calculator. Each tool covers a distinct statutory calculation or the aggregate payslip, so no tool feels redundant.

Completeness4/5

The surface covers the core monthly payroll calculations: EPF, SOCSO, SKBBK, EIS, MTD, and net pay with employer contributions. Minor gaps remain because bonuses, zakat, and non-fixed salary scenarios are explicitly excluded, but these are reasonable scope limits for the stated tool set.

Maintenance

ActivityNo data
ResponsivenessOutdated data