mcp-rupiah

An MCP server with Rupiah and Indonesian number tools for your AI assistant: terbilang (number to Indonesian words), Rupiah formatting, parsing messy amounts like Rp 1.250.000,- or 1,5 jt, and an Indonesian VAT (PPN) calculator that follows the 2025+ rules. Offline, exact decimal math, no API key, no dependencies.

Example: "Write the terbilang for Rp1.500.250 for this receipt, and how much PPN is in a total of Rp5.550.000?"

🇮🇩 Bahasa Indonesia: lihat bagian di bawah.

• One file, no dependencies: Node.js 18+, no npm install, no network, no file writes.

• Exact: all math uses BigInt decimals and fractions, so 0.1 + 0.2 style float errors never appear. Very large numbers can be sent as text.

• Honest: ambiguous input (is 1,500 one and a half or fifteen hundred?) is read the Indonesian way and the answer says how it was read.

Tools

All tools are read-only (readOnlyHint: true) and closed-world (openWorldHint: false). Numbers can be JSON numbers or text; send values of 2^53 or more as text.

Related MCP server: JP Invoice & Tax MCP

PPN (VAT) rules used by hitung_ppn

Since 1 January 2025 the PPN rate in the law is 12% (UU 7/2021 Harmonisasi Peraturan Perpajakan). The Minister of Finance regulation PMK 131 Tahun 2024 (issued 31 December 2024, in force 1 January 2025) then splits the calculation:

Worked example (nonmewah, price Rp1.000.000): DPP nilai lain = 11/12 × 1.000.000 = Rp916.666,67; PPN = 12% × 916.666,67 = Rp110.000; total Rp1.110.000.

From a total (dari: "total"): price = total ÷ 1.11, so Rp1.110.000 → price Rp1.000.000, PPN Rp110.000.

What the tool does not model, on purpose (use kategori: "custom" and pass your own rate/factor):

• PPN besaran tertentu and other nilai lain bases set by separate regulations (consolidated in PMK 11 Tahun 2025), PPN ditanggung pemerintah (DTP), exempt goods/services, and PPnBM itself.

• Older periods: before 2025 the rate was 11% (from 1 April 2022) and 10% before that. For luxury goods sold to end consumers the full 12% applies from 1 February 2025; the January 2025 transition is not modelled.

• Invoice rounding rules (e-Faktur) are not modelled: by default values are shown to the sen; pembulatan (bawah, terdekat, atas) rounds the PPN to whole Rupiah if you need it.

Sources (checked 11 November 2026):

• PMK 131 Tahun 2024 and the DJP article "PMK 131/2024: Tarif PPN Sebelas-Dua Belas", 6 January 2025, pajak.go.id.

• DJP press release on PMK 11/2025 (DPP nilai lain and PPN besaran tertentu), pajak.go.id.

• DDTCNews, 17 August 2025: the Ministry of Finance confirms 12% for luxury goods and 12% × 11/12 for other goods in 2026, news.ddtc.co.id.

• DDTCNews, 10 September 2026: the Minister of Finance says the general PPN rate stays at 12%, news.ddtc.co.id.

If the rules change, kategori: "custom" keeps working while the defaults are updated. This is a calculation aid, not tax advice.

Install

With npx (recommended): nothing to install. The configs below run npx -y mcp-rupiah.

From source:

git clone https://github.com/EzkielynaGroup/mcp-rupiah.git
cd mcp-rupiah
node --test test/        # optional: offline tests

Then use "command": "node" with "args": ["/full/path/to/mcp-rupiah.mjs"] instead of npx.

On Windows, if the app cannot start npx, use "command": "cmd" with "args": ["/c", "npx", "-y", "mcp-rupiah"].

Claude Desktop

Settings → Developer → Edit Config (claude_desktop_config.json), then fully quit and reopen Claude Desktop.

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

Claude Code

claude mcp add rupiah -- npx -y mcp-rupiah

Add --scope user to make it available in every project. Check with claude mcp list.

Cursor

~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project), same JSON as Claude Desktop.

OpenCode

opencode.json in the project, or ~/.config/opencode/opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "rupiah": {
      "type": "local",
      "command": ["npx", "-y", "mcp-rupiah"],
      "enabled": true
    }
  }
}

Configuration

No environment variables and no API key. The server never opens a network connection and never writes files.

Reading rules for text input

• . is the thousands separator and , the decimal mark (Indonesian style): 1.250.000,50 = 1250000.5.

• If both appear, the last one is the decimal mark, so English 1,234,567.89 also works (the answer notes it).

• A single , is always a decimal mark: 1,500 = 1.5 (with a note). A single . followed by exactly three digits is a thousands separator: 1.500 = 1500; otherwise it is a decimal point: 1.5 = 1.5.

• M means miliar (10^9) as in Indonesian; a lowercase m is also read as miliar, with a note (write jt for million).

• Plain digit strings ("1234.5") and scientific notation ("1.5e3") are read as numbers.

Limits

• terbilang names numbers below 10^18 (up to 999 kuadriliun) with up to 20 decimal digits.

• Text input is limited to 2,000 characters.

• JSON numbers above 2^53 are refused because their precision is already lost; send them as text.

FAQ

How do I write terbilang for Rp1.500.000 in Indonesian? Satu juta lima ratus ribu rupiah. Call terbilang with rupiah: true; add huruf: "judul" for Satu Juta Lima Ratus Ribu Rupiah on a receipt (kuitansi).

Is it "seribu" or "satu ribu", "seratus" or "satu ratus"? 1,000 is seribu and 100 is seratus, also inside bigger numbers (seratus satu ribu, satu juta seribu). From a million up, satu is used: satu juta, satu miliar.

How is PPN 12% calculated in 2025 and 2026? For most goods and services: 12% × DPP nilai lain, where DPP nilai lain = 11/12 of the price, so the PPN is effectively 11% of the price (PMK 131/2024). Only luxury goods subject to PPnBM pay 12% of the full price.

How do I get the price before PPN from a total that includes PPN? For non-luxury goods divide by 1.11 (price = total ÷ 1.11, PPN = total − price). hitung_ppn with dari: "total" does this exactly.

How do I format a number as Rupiah, like Rp1.234.567,89? Use format_rupiah: dots for thousands, comma for decimals, Rp with no space (Indonesian spelling rules). ringkas: true gives short forms such as Rp1,2 jt.

How do I convert "1,5 jt" or "Rp 1.250.000,-" to a number? parse_rupiah returns 1500000 and 1250000. It also reads amounts written in words.

Development

node --test test/

18 test groups (unit tests including a terbilang → words-parser round trip over 300+ numbers, plus end-to-end tests over MCP stdio), offline. Issues and pull requests are welcome.

Bahasa Indonesia

Server MCP berisi alat Rupiah dan angka Indonesia untuk asisten AI (Claude Desktop, Claude Code, Cursor, OpenCode): terbilang, format Rupiah, membaca nominal dari teks berantakan, dan kalkulator PPN sesuai aturan 2025+. Offline, hitungan desimal tepat, tanpa API key, tanpa dependensi.

Contoh: "Tuliskan terbilang Rp1.500.250 untuk kuitansi, dan berapa PPN dari total Rp5.550.000?"

Tools

Aturan PPN (sejak 1 Januari 2025, PMK 131 Tahun 2024):

• Bukan barang mewah (default nonmewah): PPN = 12% × DPP nilai lain, DPP nilai lain = 11/12 × harga jual/penggantian/nilai impor → efektif 11%. Contoh: harga Rp1.000.000 → DPP Rp916.666,67 → PPN Rp110.000 → total Rp1.110.000.

• Barang mewah objek PPnBM (mewah): PPN = 12% × harga jual → efektif 12% (penjualan eceran ke konsumen akhir mulai 1 Februari 2025). PPnBM tidak dihitung.

• Skema khusus (PPN besaran tertentu, nilai lain selain 11/12, PPN DTP, barang/jasa dibebaskan, periode sebelum 2025): pakai kategori: "custom" dengan tarif_persen dan faktor_dpp sendiri.

• Sumber: PMK 131/2024; artikel DJP "PMK 131/2024: Tarif PPN Sebelas-Dua Belas" (6 Jan 2025); siaran pers DJP tentang PMK 11/2025; DDTCNews 17 Agu 2025 dan 10 Sep 2026 (tarif umum tetap 12%). Dicek 11 November 2026. Alat bantu hitung, bukan nasihat pajak.

Instalasi: sama seperti contoh di atas. Claude Code: claude mcp add rupiah -- npx -y mcp-rupiah. Windows: "command": "cmd", "args": ["/c", "npx", "-y", "mcp-rupiah"]. Tidak ada variabel lingkungan atau API key.

Aturan membaca teks: titik = ribuan, koma = desimal. 1.500 dibaca 1500, 1,500 dibaca 1,5 (dengan catatan). M = miliar. Angka sangat besar (≥ 2^53) kirim sebagai teks.

Tanya jawab

• Terbilang Rp1.500.000? "Satu juta lima ratus ribu rupiah" (terbilang dengan rupiah: true, huruf: "judul" untuk kuitansi).

• Seribu atau satu ribu? 1.000 = seribu, 100 = seratus; mulai juta memakai satu: satu juta.

• Cara hitung PPN 12% tahun 2025/2026? Umumnya 12% × 11/12 × harga = 11% dari harga; barang mewah 12% dari harga penuh.

• Cara mencari harga sebelum PPN dari total? Untuk barang bukan mewah: harga = total ÷ 1,11 (hitung_ppn dengan dari: "total").

License

MIT. See LICENSE.

Made by Ezkielyna, an independent AI API gateway for Indonesian developers (pay with QRIS).