mcp-wilayah-indonesia

An MCP server that lets your AI assistant look up Indonesian administrative regions and their Kemendagri codes: provinsi, kabupaten/kota, kecamatan (distrik) and desa/kelurahan. It works offline from a bundled copy of the current code list (Kepmendagri No. 300.2.2-2430 Tahun 2025, 91,599 regions) and tolerates typos.

Example: "What is the Kemendagri code of Kelurahan Kemayoran in Jakarta Pusat, and which BMKG adm4 code do I use for its weather forecast?"

🇮🇩 Bahasa Indonesia: lihat bagian di bawah.

• One file, no dependencies: only Node.js 18 or newer. The data (≈ 660 KB gzip) ships with the package.

• No API key, no network calls, no cost. Read-only: the server never writes files.

• Full path in every answer, e.g. Kel. Kemayoran, Kec. Kemayoran, Kota Adm. Jakarta Pusat, Prov. Daerah Khusus Ibukota Jakarta.

• Accepts codes with or without dots (31.71.03.1001 or 3171031001).

Tools

Every tool is read-only (readOnlyHint: true, openWorldHint: false). Answers are JSON text plus structuredContent.

Code format

Related MCP server: Pasal — Indonesian Law

Works with BMKG weather (adm4)

BMKG's public weather forecast API identifies villages by the same level-4 Kemendagri code with dots, as the adm4 parameter, e.g. https://api.bmkg.go.id/publik/prakiraan-cuaca?adm4=31.71.03.1001 (checked 11 Nov 2026). Level-4 results therefore include a bmkg_adm4 field. Pair this server with mcp-bmkg so the assistant can go from "weather in Kemayoran tomorrow" to the right village code to the forecast.

Install

With npx (recommended): nothing to install. The configs below run npx -y mcp-wilayah-indonesia, which downloads the package (one .mjs file plus the data file, no dependencies) on first start.

From source:

git clone https://github.com/EzkielynaGroup/mcp-wilayah-indonesia.git
cd mcp-wilayah-indonesia
node --test test/        # optional, offline

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

On Windows, if the app cannot start npx, use "command": "cmd" with "args": ["/c", "npx", "-y", "mcp-wilayah-indonesia"]. Write paths in JSON with forward slashes (C:/Users/you/mcp-wilayah-indonesia/mcp-wilayah-indonesia.mjs) or double backslashes.

Claude Desktop

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

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

Claude Code

claude mcp add wilayah-indonesia -- npx -y mcp-wilayah-indonesia

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 for all projects.

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

Configuration (environment)

Safety and limits

• Offline and read-only: no network requests, no file writes. Logs go to stderr; stdout carries only MCP messages.

• Input limits: names up to 200 characters, up to 50 search results and 200 children per page.

• Errors come back as short tool errors (Indonesian + English) without stack traces or local paths.

• The data is a snapshot. Codes and names change when regions split or are renamed; check the decree itself for legal or administrative use.

Data source and license

Notes: the comment header inside the upstream SQL file still mentions No. 300.2.2-2138 while the upstream README and its change notes say the data follows No. 300.2.2-2430; we follow the README. The province name for Jakarta is kept as it appears in the list (Daerah Khusus Ibukota Jakarta). This project has not compared every row against the decree PDF itself.

To rebuild after an upstream update:

curl -sL -o /tmp/wilayah.sql https://raw.githubusercontent.com/cahyadsn/wilayah/master/db/wilayah.sql
node scripts/build-data.mjs /tmp/wilayah.sql --commit <upstream sha> --date <YYYY-MM-DD>
node --test test/

FAQ

What is the Kemendagri code of my village (kode desa / kode kelurahan)? Ask your assistant with this server enabled, e.g. "kode wilayah Desa Sukamaju, Kec. Cilawu, Garut". cari_wilayah returns the 10-digit code (32.05.19.2014) and the full path.

Is this the same code BMKG uses for weather (adm4)? Yes. BMKG's forecast API takes the level-4 Kemendagri code with dots as adm4, so bmkg_adm4 can be passed straight to it or to mcp-bmkg.

How many provinces, regencies and villages does Indonesia have in the current list? Per Kepmendagri 300.2.2-2430/2025: 38 provinces, 416 kabupaten, 98 kota, 7,285 kecamatan, 8,496 kelurahan and 75,266 desa.

Is this the same as the postal code (kode pos) or the BPS code? No. Kemendagri region codes are different from postal codes, and from BPS (statistics) codes below the province level, which can differ (for example Kota Jakarta Pusat). This server only knows Kemendagri codes.

Does it need internet or an API key? No. The data is bundled; after npx has downloaded the package once, everything runs locally and costs nothing.

Is this data published by the government? The codes come from a Kemendagri decree, but this package uses an MIT-licensed community compilation of it, not a government service. For legal or administrative documents, check the decree published by Kemendagri.

Development

node --test test/

11 tests spawn the server over stdio against a 46-row fixture taken from the real data (every tool, filters, typos, pagination, error paths, broken data files) and check that the bundled full list loads with the published totals. No network.

License

Code: MIT, Copyright (c) 2026 Ezekiel Lieberhart (Ezkielyna). Data: MIT, Copyright (c) 2017-2025 Cahya DSN (see data/LICENSE-DATA.txt). This project is not affiliated with Kemendagri, BMKG or the upstream dataset author.

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

Bahasa Indonesia

Server MCP agar asisten AI (Claude Desktop, Claude Code, Cursor, OpenCode, dan klien MCP lain) bisa mencari wilayah administrasi Indonesia beserta kode Kemendagri-nya: provinsi, kabupaten/kota, kecamatan (distrik) dan desa/kelurahan. Berjalan offline dari salinan daftar kode terbaru (Kepmendagri No. 300.2.2-2430 Tahun 2025, 91.599 wilayah) dan tahan salah ketik.

Contoh pertanyaan: "Apa kode wilayah Kelurahan Kemayoran, Jakarta Pusat? Kode adm4 BMKG-nya apa?"

• Cukup Node.js 18+, tanpa dependensi, tanpa API key, tanpa internet setelah paket terunduh, gratis.

• Setiap hasil memuat path lengkap, misalnya Desa Sukamaju, Kec. Cilawu, Kab. Garut, Prov. Jawa Barat.

• Kode boleh ditulis dengan atau tanpa titik (31.71.03.1001 atau 3171031001).

Tool

Pasangan dengan BMKG

API prakiraan cuaca publik BMKG memakai kode desa/kelurahan Kemendagri bertitik sebagai parameter adm4, misalnya https://api.bmkg.go.id/publik/prakiraan-cuaca?adm4=31.71.03.1001. Hasil tingkat 4 punya kolom bmkg_adm4. Pakai bersama mcp-bmkg: asisten mencari kode desa di sini, lalu mengambil prakiraan cuacanya di sana.

Pasang

Tambahkan ke konfigurasi aplikasi (sama seperti contoh di atas):

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

Claude Code: claude mcp add wilayah-indonesia -- npx -y mcp-wilayah-indonesia. Di Windows, bila npx tidak jalan, pakai "command": "cmd" dan "args": ["/c", "npx", "-y", "mcp-wilayah-indonesia"].

Sumber data dan lisensi

Data diambil dari repositori cahyadsn/wilayah (lisensi MIT, Copyright (c) 2017-2025 Cahya DSN), file db/wilayah.sql commit d68e8d5 (perubahan data terakhir 13 Feb 2026, diunduh 11 Nov 2026), yang menurut README-nya mengikuti Kepmendagri No. 300.2.2-2430 Tahun 2025. Jumlahnya cocok dengan tabel di README sumber: 38 provinsi, 416 kabupaten, 98 kota, 7.285 kecamatan, 8.496 kelurahan, 75.266 desa. Kami tidak mencocokkan setiap baris dengan PDF Kepmendagri. Untuk keperluan hukum atau administrasi, rujuk dokumen Kepmendagri yang diterbitkan Kemendagri.

Tanya jawab

• Bagaimana cara cari kode desa? Tanyakan ke asisten, misalnya "kode wilayah Desa Sukamaju Cilawu Garut"; cari_wilayah memberi kode 10 digit dan path lengkap.

• Apakah sama dengan kode pos? Tidak. Kode wilayah Kemendagri berbeda dengan kode pos dan kode BPS.

• Perlu internet atau API key? Tidak. Data ikut dalam paket dan semuanya gratis.

Kode: MIT. Data: MIT (Cahya DSN). Dibuat oleh Ezkielyna, gateway API AI independen untuk developer Indonesia (bayar pakai QRIS).

Part of the Ezkielyna developer toolkit

Open-source tools from Ezkielyna, an independent OpenAI- and Anthropic-compatible AI API gateway (pay with QRIS, USDT or Binance Pay; no credit card).

More: all repositories · awesome-mcp-indonesia · awesome-ai-indonesia