BMKG

You run an MCP server that exposes BMKG data—earthquakes, weather forecasts, and early warnings—so clients can fetch reliable Indonesian region data through a standardized MCP interface. This guide shows how to install, configure, and use the BMKG MCP Server so you can build powerful data access into your applications.

How to use

You operate the server in your environment and then connect MCP clients to it to request data. The server provides tools for current earthquakes, recent significant quakes, felt earthquakes, 3-day weather forecasts by region, and active weather alerts with CAP-based details. For location-aware data, you can search region codes, list villages in a district, and retrieve 3-day weather forecasts down to the village level.

How to install

# Prerequisites
python3 --version
uv --version 2>/dev/null || true
# Install a local MCP client helper (optional, for testing)
# The server itself runs as a local process via Python or uv

# Step 1: Get the server sources
git clone https://github.com/revomkg/bmkg-mcp.git
cd bmkg-mcp

# Step 2: Install runtime dependencies if you will run via Python or uvx
# Using uvx (preferred for speed)
uv sync

# Alternatively, with pip (if you prefer Python's ecosystem)
pip install httpx xmltodict mcp

# Step 3: Ensure base data file exists if required by your setup
# Place base.csv in the same directory as bmkg-server.py

# Step 4: Run the server (examples shown in the configuration snippets)
# See the configuration blocks below for exact invocation

Configuration and runtime

You can run the BMKG MCP Server locally using one of two common runtimes. Choose the method that matches your environment and workflow. The server entry point is a Python script named bmkg-server.py. You can start it directly with Python, or via uv to integrate with a local MCP toolchain.

{
  "mcpServers": {
    "bmkg": {
      "command": "python",
      "args": ["/path/to/bmkg-mcp/bmkg-server.py"]
    }
  }
}

Alternative startup with uv

{
  "mcpServers": {
    "bmkg": {
      "command": "uv",
      "args": ["run", "/path/to/bmkg-mcp/bmkg-server.py"]
    }
  }
}

Notes on usage and data access

• Data endpoints provide earthquake information, weather forecasts, and weather alerts sourced from BMKG data streams. - Location-based queries rely on a local area code database and hierarchical region mapping. - Weather alerts follow the Common Alerting Protocol (CAP) with bilingual (Indonesia and English) details where available. - Access may be subject to rate limits from BMKG sources, so use responsibly in high-frequency scenarios.

Troubleshooting and tips

• Ensure base.csv is present in the same directory as bmkg-server.py if your setup requires a local region code database. - If you encounter issues starting the server with Python, verify you have Python 3.8+ installed and the required dependencies. - If you prefer a local dev workflow, using uv can simplify integration with MCP clients that expect stdio-based servers.

Security and usage limits

• Respect rate limits for weather forecasts and weather alerts per IP as published for BMKG sources. - Do not expose sensitive internal paths or system details publicly. - Use secure configurations for any API keys or local access controls if you extend the server with additional endpoints.

Tools available through the MCP surface

The server exposes a set of functions you can call from MCP clients to retrieve current events and forecasts. Key tools include:

• get_latest_earthquake(): fetches the most recent earthquake data with shakemap
• get_significant_earthquakes(): returns the 15 latest earthquakes with magnitude 5.0+ and tsunami potential
• get_felt_earthquakes(): lists earthquakes felt by communities and affected regions
• search_location_code(location_name, admin_level): locate a region code by name and administrative level
• get_villages_in_district(district_code): list all villages in a district with codes
• get_weather_forecast(kode_wilayah): 3-day forecast with humidity, wind, cloud cover, visibility, and temperatures
• get_weather_alerts(language): active weather alerts with CAP links
• get_weather_alert_detail(cap_code, language): detailed CAP alert information
• search_weather_alerts_by_kecamatan(kecamatan, language): alerts for a specific district " ,

What to put in your environment

No mandatory environment variables are shown for running the server in the provided setup. If you introduce external services or credentials, document them clearly in your deployment environment and keep them secure.

Related data sources

Data originates from BMKG data streams for earthquakes and weather, accessed via BMKG API endpoints. The location code database uses a locally maintained dataset. Always ensure you comply with BMKG terms of use when building applications on top of these data sources.

Available tools

get_latest_earthquake

Fetches the most recent earthquake data with shakemap, including time, magnitude, depth, location, tsunami potential, and shakemap URL.

get_significant_earthquakes

Returns the latest 15 earthquakes with magnitude 5.0+ and tsunami potential for each event.

get_felt_earthquakes

Lists the 15 earthquakes felt by people, with affected regions included.

search_location_code

Finds a region code by location name and optional administrative level such as province, regency, district, or village.

get_villages_in_district

Retrieves all villages within a specified district code, returning complete village codes.

get_weather_forecast

Provides a 3-day weather forecast for a given region code with 8 forecasts per day, including temperature, humidity, weather, wind, cloud cover, and visibility.

get_weather_alerts

Returns active weather alerts as an RSS feed and links to CAP details by province.

get_weather_alert_detail

Displays detailed CAP alert information for a given CAP code, with affected districts and timing details.

search_weather_alerts_by_kecamatan

Finds weather alerts affecting a specific district, with language support.