bmkg-api-mcp 1.0.2

MCP Server for BMKG Indonesia - Weather, Earthquake, and Region Data for AI Assistants

BMKG API

English | Bahasa Indonesia

---

🇬🇧 English

Free REST API for Indonesian weather forecasts, earthquake data, weather warnings, and region lookup from BMKG.

🌐 Demo: https://bmkg-restapi.vercel.app

⚠️ Important Notice

This is a demo/public instance with rate limits (30 requests/minute) to ensure fair usage.

For production use with unlimited requests, please self-host.

Features

• 🌍 Earthquake Data — Latest, recent (M 5.0+), felt earthquakes, nearby search by coordinates
• 🌤️ Weather Forecast — 3-day forecasts & current weather for any kelurahan/desa in Indonesia
• ⚠️ Weather Warnings (Nowcast) — Real-time severe weather alerts with affected area polygons
• 📍 Region Lookup — Indonesian provinces, districts, subdistricts, villages, plus search
• 📊 Auto-generated Docs — Interactive API documentation at /docs
• ⚡ Caching — Fast responses with in-memory cache (configurable TTL)
• 🌐 CORS Enabled — Use from any frontend
• 🔓 No API Key Required — Simple, anonymous access
• 📈 Rate Limit Headers — X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset on every response
• 🐳 Docker & GHCR — Automated multi-arch Docker images published to GitHub Container Registry
• 🤖 MCP Server — Model Context Protocol for AI assistants (Claude, Cursor, etc.)

Quick Start

# Latest earthquake
curl https://bmkg-restapi.vercel.app/v1/earthquake/latest

# Weather forecast for Pejaten Barat, Pasar Minggu, Jakarta Selatan
curl https://bmkg-restapi.vercel.app/v1/weather/31.74.04.1006

# Current weather
curl https://bmkg-restapi.vercel.app/v1/weather/31.74.04.1006/current

# Active weather warnings
curl https://bmkg-restapi.vercel.app/v1/nowcast

# Search regions
curl https://bmkg-restapi.vercel.app/v1/wilayah/search?q=tebet

API Endpoints

🌍 Earthquake

Endpoint	Description
GET /v1/earthquake/latest	Latest earthquake
GET /v1/earthquake/recent	Recent earthquakes (M 5.0+)
GET /v1/earthquake/felt	Felt earthquakes
GET /v1/earthquake/nearby?lat=&lon=&radius_km=	Nearby earthquakes

🌤️ Weather

Endpoint	Description
GET /v1/weather/{adm4_code}	3-day forecast for a kelurahan/desa
GET /v1/weather/{adm4_code}/current	Current weather for a kelurahan/desa

⚠️ Nowcast (Weather Warnings)

Endpoint	Description
GET /v1/nowcast	Active weather warnings by province
GET /v1/nowcast/{alert_code}	Warning detail with affected area polygons
GET /v1/nowcast/check?location=	Check warnings for a specific location

📍 Wilayah (Region)

Endpoint	Description
GET /v1/wilayah/provinces	List provinces
GET /v1/wilayah/districts?province_code=	List districts
GET /v1/wilayah/subdistricts?district_code=	List subdistricts
GET /v1/wilayah/villages?subdistrict_code=	List villages
GET /v1/wilayah/search?q={query}	Search regions

Full documentation: https://bmkg-restapi.vercel.app/docs

🤖 MCP Server (for AI Assistants)

Use BMKG data directly in Claude Desktop, Cursor, VS Code, Windsurf, Zed, and other MCP-compatible AI assistants.

Installation

# Via pipx (recommended)
pipx install bmkg-api-mcp

# Via pip
pip install bmkg-api-mcp

Quick Setup

Claude Desktop:

# Edit config file
nano ~/Library/Application\ Support/Claude/claude_desktop_config.json

Add this to your config:

{
  "mcpServers": {
    "bmkg-api": {
      "command": "bmkg-api-mcp"
    }
  }
}

Cursor:

1. Open Settings → Features → MCP Servers
2. Click "Add New MCP Server"
3. Name: bmkg-api, Type: command, Command: bmkg-api-mcp

VS Code (Cline/Roo Code):

{
  "mcpServers": {
    "bmkg-api": {
      "command": "bmkg-api-mcp",
      "disabled": false,
      "autoApprove": []
    }
  }
}

Available Tools (15)

Category	Tools
🌍 Earthquake	get_latest_earthquake, get_recent_earthquakes, get_felt_earthquakes, get_nearby_earthquakes
🌤️ Weather	get_weather_forecast, get_current_weather
⚠️ Nowcast	get_weather_warnings, check_location_warnings
📍 Region	search_regions, get_provinces, get_districts, get_subdistricts, get_villages
🔧 Utility	get_cache_stats, debug_ping

Example Prompts

Try these natural language queries in your AI assistant:

"Gempa terbaru di Indonesia berapa magnitudenya?"
"Cuaca 3 hari ke depan di Jakarta Selatan?"
"Cari kode wilayah untuk Kelapa Gading"
"Ada peringatan cuaca ekstrem di Yogyakarta?"
"Gempa dengan magnitud di atas 5 derajat minggu ini?"
"Bandung ada gempa dekat-dekat sini?"

Features

• ⚡ Caching — Smart TTL-based caching for optimal performance
• 🐛 Debug Mode — Run bmkg-api-mcp --debug for verbose logging
• 🔌 7 Specialized Prompts — Earthquake, weather, region, emergency, travel, research, and daily briefing assistants

📖 Full Setup Guide: See MCP_SETUP.md for detailed configuration for all supported IDEs.

Self-Hosting

Option 1: Docker (Recommended)

# Pull from GitHub Container Registry
docker pull ghcr.io/dhanyyudi/bmkg-api:latest

# Or build and run with Docker Compose
git clone https://github.com/dhanyyudi/bmkg-api.git
cd bmkg-api
docker-compose up -d

Option 2: Local Development

git clone https://github.com/dhanyyudi/bmkg-api.git
cd bmkg-api
make setup
source venv/bin/activate
make dev     # starts server on http://localhost:8099

Option 3: Vercel (Serverless)

Deploy to Vercel with one click — the api/index.py and vercel.json are pre-configured.

See Self-Hosting Guide for detailed instructions.

Code Examples

Available on the landing page for: cURL, JavaScript, Python, Go, PHP, Ruby, and Dart (Flutter).

---

🇮🇩 Bahasa Indonesia

API REST gratis untuk prakiraan cuaca, data gempa bumi, peringatan cuaca, dan pencarian wilayah Indonesia dari BMKG.

🌐 Demo: https://bmkg-restapi.vercel.app

⚠️ Pemberitahuan Penting

Ini adalah instance demo/publik dengan batasan rate limit (30 request/menit).

Untuk penggunaan produksi dengan request tanpa batas, silakan self-host.

Fitur

• 🌍 Data Gempa — Gempa terbaru, terkini (M 5.0+), dirasakan, pencarian radius
• 🌤️ Prakiraan Cuaca — 3 hari & cuaca saat ini untuk lokasi mana pun di Indonesia
• ⚠️ Peringatan Cuaca (Nowcast) — Peringatan dini real-time dengan poligon area terdampak
• 📍 Pencarian Wilayah — Provinsi, kabupaten, kecamatan, desa, plus pencarian
• 📊 Dokumentasi Auto — Dokumentasi API interaktif di /docs
• ⚡ Caching — Response cepat dengan cache lokal (TTL bisa dikonfigurasi)
• 🌐 CORS Enabled — Bisa dipakai dari frontend mana saja
• 🔓 Tanpa API Key — Akses sederhana dan anonim
• 📈 Rate Limit Headers — X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset di setiap response
• 🐳 Docker & GHCR — Image Docker multi-arsitektur otomatis di GitHub Container Registry
• 🤖 MCP Server — Model Context Protocol untuk AI assistants (Claude, Cursor, dll)

Cepat Mulai

# Gempa terbaru
curl https://bmkg-restapi.vercel.app/v1/earthquake/latest

# Prakiraan cuaca Pejaten Barat, Pasar Minggu, Jakarta Selatan
curl https://bmkg-restapi.vercel.app/v1/weather/31.74.04.1006

# Cuaca saat ini
curl https://bmkg-restapi.vercel.app/v1/weather/31.74.04.1006/current

# Peringatan cuaca aktif
curl https://bmkg-restapi.vercel.app/v1/nowcast

# Cari wilayah
curl https://bmkg-restapi.vercel.app/v1/wilayah/search?q=wiradesa

Endpoint API

🌍 Gempa Bumi

Endpoint	Deskripsi
GET /v1/earthquake/latest	Gempa terbaru
GET /v1/earthquake/recent	Gempa terkini (M 5.0+)
GET /v1/earthquake/felt	Gempa dirasakan
GET /v1/earthquake/nearby?lat=&lon=&radius_km=	Gempa terdekat

🌤️ Cuaca

Endpoint	Deskripsi
GET /v1/weather/{adm4_code}	Prakiraan 3 hari
GET /v1/weather/{adm4_code}/current	Cuaca saat ini

⚠️ Nowcast (Peringatan Cuaca)

Endpoint	Deskripsi
GET /v1/nowcast	Peringatan cuaca aktif per provinsi
GET /v1/nowcast/{alert_code}	Detail peringatan dengan poligon area
GET /v1/nowcast/check?location=	Cek peringatan untuk lokasi tertentu

📍 Wilayah

Endpoint	Deskripsi
GET /v1/wilayah/provinces	Daftar provinsi
GET /v1/wilayah/districts?province_code=	Daftar kabupaten/kota
GET /v1/wilayah/subdistricts?district_code=	Daftar kecamatan
GET /v1/wilayah/villages?subdistrict_code=	Daftar desa/kelurahan
GET /v1/wilayah/search?q={query}	Cari wilayah

Dokumentasi lengkap: https://bmkg-restapi.vercel.app/docs

🤖 MCP Server (untuk AI Assistants)

Gunakan data BMKG langsung di Claude Desktop, Cursor, VS Code, Windsurf, Zed, dan AI assistants lain yang kompatibel dengan MCP.

Instalasi

# Via pipx (direkomendasikan)
pipx install bmkg-api-mcp

# Via pip
pip install bmkg-api-mcp

Setup Cepat

Claude Desktop:

# Edit file config
nano ~/Library/Application\ Support/Claude/claude_desktop_config.json

Tambahkan ke config:

{
  "mcpServers": {
    "bmkg-api": {
      "command": "bmkg-api-mcp"
    }
  }
}

Cursor:

1. Buka Settings → Features → MCP Servers
2. Klik "Add New MCP Server"
3. Name: bmkg-api, Type: command, Command: bmkg-api-mcp

VS Code (Cline/Roo Code):

{
  "mcpServers": {
    "bmkg-api": {
      "command": "bmkg-api-mcp",
      "disabled": false,
      "autoApprove": []
    }
  }
}

Tools Tersedia (15)

Kategori	Tools
🌍 Gempa	get_latest_earthquake, get_recent_earthquakes, get_felt_earthquakes, get_nearby_earthquakes
🌤️ Cuaca	get_weather_forecast, get_current_weather
⚠️ Nowcast	get_weather_warnings, check_location_warnings
📍 Wilayah	search_regions, get_provinces, get_districts, get_subdistricts, get_villages
🔧 Utility	get_cache_stats, debug_ping

Contoh Prompt

Coba query bahasa alami ini di AI assistant Anda:

"Gempa terbaru di Indonesia berapa magnitudenya?"
"Cuaca 3 hari ke depan di Jakarta Selatan?"
"Cari kode wilayah untuk Kelapa Gading"
"Ada peringatan cuaca ekstrem di Yogyakarta?"
"Gempa dengan magnitud di atas 5 derajat minggu ini?"
"Bandung ada gempa dekat-dekat sini?"

Fitur

• ⚡ Caching — Caching cerdas dengan TTL untuk performa optimal
• 🐛 Debug Mode — Jalankan bmkg-api-mcp --debug untuk logging detail
• 🔌 7 Prompt Spesialis — Asisten gempa, cuaca, wilayah, darurat, travel, riset, dan briefing harian

📖 Panduan Lengkap: Lihat MCP_SETUP.md untuk konfigurasi detail semua IDE yang didukung.

Self-Hosting

Opsi 1: Docker (Direkomendasikan)

# Pull dari GitHub Container Registry
docker pull ghcr.io/dhanyyudi/bmkg-api:latest

# Atau build dan jalankan dengan Docker Compose
git clone https://github.com/dhanyyudi/bmkg-api.git
cd bmkg-api
docker-compose up -d

Opsi 2: Lokal

git clone https://github.com/dhanyyudi/bmkg-api.git
cd bmkg-api
make setup
source venv/bin/activate
make dev     # jalankan server di http://localhost:8099

Opsi 3: Vercel (Serverless)

Deploy ke Vercel — api/index.py dan vercel.json sudah dikonfigurasi.

Lihat Panduan Self-Hosting untuk detail.

Contoh Kode

Tersedia di halaman utama untuk: cURL, JavaScript, Python, Go, PHP, Ruby, dan Dart (Flutter).

---

Data Source

All data is sourced from BMKG (Badan Meteorologi, Klimatologi, dan Geofisika).

Attribution

This API is not affiliated with BMKG. All data belongs to BMKG.

License

MIT License — see LICENSE

---

Built with ❤️ by dhanypedia