Wilayah Indonesia

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

Tool	What it does
cari_wilayah	Search by name, typo tolerant. Extra words can name a parent ("sukamaju garut"), a leading kab/kota/kec/desa/kel is used as a hint, common short names work (jogja, DKI, jatim, NTT). Filters: tingkat (1–4), jenis (provinsi, kabupaten, kota, kecamatan, kelurahan, desa), kode_induk (search inside a parent), batas (max 50). Returns code, kind, level, full path and a score.
detail_kode	Code → name, kind, every parent from the province down, and how many regions sit below it.
daftar_anak	Direct children of a code (province → kabupaten/kota → kecamatan → desa/kelurahan), paginated with offset and batas (max 200). Without a code it lists the 38 provinces.
validasi_kode	Checks the format (2/4/6/10 digits, segment rules such as kota = 71–79, kelurahan = 1xxx, desa = 2xxx, desa adat = 3xxx) and whether the code exists. For an unknown code it names the nearest parent that does exist; island codes (xx.xx.4xxxx) are recognised and explained.

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

Code format

Level	Kind	Digits	Example
1	provinsi	2	32 Jawa Barat
2	kabupaten (01–69) / kota (71–79)	2.2	32.73 Kota Bandung
3	kecamatan (called distrik in the Papua provinces)	2.2.2	32.73.01 Sukasari
4	kelurahan (1xxx) / desa (2xxx; 3xxx for the 14 desa adat in Kab. Jayapura)	2.2.2.4	31.71.03.1001 Kemayoran

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)

Variable	Required	Default	Notes
WILAYAH_DATA_FILE	no	bundled data/wilayah.json.gz	Use another data file (.json or .json.gz) with the same shape, e.g. a newer build made with scripts/build-data.mjs.

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

Legal basis	Keputusan Menteri Dalam Negeri No. 300.2.2-2430 Tahun 2025 (amends No. 300.2.2-2138 Tahun 2025), as stated by the upstream dataset
Dataset	cahyadsn/wilayah, file db/wilayah.sql, commit d68e8d5 (last data change 13 Feb 2026), downloaded 11 Nov 2026
Dataset license	MIT, Copyright (c) 2017-2025 Cahya DSN. The full notice ships as data/LICENSE-DATA.txt.
Contents	38 provinsi, 416 kabupaten, 98 kota, 7,285 kecamatan, 8,496 kelurahan, 75,266 desa (91,599 rows). These totals were checked against the table in the upstream README.
Changes	Converted to compact JSON + gzip; 5 names had a trailing space removed. Nothing else changed.

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

Tool	Fungsi
cari_wilayah	Cari berdasarkan nama (tahan salah ketik). Kata tambahan bisa berupa nama induk ("sukamaju garut"); awalan kab/kota/kec/desa/kel dipakai sebagai petunjuk; singkatan umum dikenali (jogja, DKI, jatim, NTT). Filter: tingkat (1–4), jenis, kode_induk, batas (maks 50).
detail_kode	Kode → nama, jenis, semua induk dari provinsi ke bawah, dan jumlah wilayah di bawahnya.
daftar_anak	Daftar wilayah satu tingkat di bawah kode, dengan halaman (offset, batas maks 200). Tanpa kode: 38 provinsi.
validasi_kode	Cek format (2/4/6/10 digit, kota = 71–79, kelurahan = 1xxx, desa = 2xxx, desa adat = 3xxx) dan apakah kode ada. Untuk kode yang tidak ada, disebutkan induk terdekat yang ada. Kode pulau (xx.xx.4xxxx) dikenali.

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).