io.github.do-droid/busan-essentials

Busan Essentials — MCP Server

Find the nearest restroom, pharmacy, free WiFi, AED, or tourist information center in Busan, South Korea. 8,680 places from Korean government open data, every record in both Korean and English.

What is this?

Busan Essentials is an MCP (Model Context Protocol) server that answers "where is the nearest X in Busan?" for AI agents helping travellers and residents. Every record carries a Korean and English name and address, so an agent can hand the Korean text to a taxi driver and the English to the traveller.

Available Data

8,680 places live across all 16 Busan districts, sourced from data.go.kr. Each record has GPS coordinates, opening hours, accessibility flags, and a trust_score.

Not covered: subway and bus timetables, taxis, restaurants, hotels, attractions, and anywhere outside Busan. get_subway_timetable is registered but has no data loaded — see Known Data Limitations.

MCP Tools

find_places

Search by type, district, and attributes. Use find_nearby instead when the user has a location or asks for the nearest one.

Parameters:

• type (required): "toilet" | "pharmacy" | "wifi" | "aed" | "tourist_info"
• district (optional): Busan district name in English or Korean (e.g., "haeundae", "해운대구")

• filters (optional): Attribute filters, all of which must match. Only these exist:

  Type	Filter	Matching records
  toilet	{"wheelchair": true}	1,050 of 2,487
  toilet	{"is_24h": true}	839 of 2,487
  toilet	{"diaper_table": true}	433 of 2,487
  tourist_info	{"english": true}	14 of 25
  tourist_info	{"chinese": true}	13 of 25
  tourist_info	{"japanese": true}	9 of 25

  pharmacy, wifi, and aed carry no usable filter — the upstream sources record no per-facility variation. An unknown filter key returns zero results rather than being ignored.

• limit (optional): Max results, 1-50 (default: 10)

get_place_detail

Get the full record for one facility by its ID. IDs come from find_places or find_nearby — don't guess them.

Parameters:

• id (required): Place ID (e.g., "toilet_00001", "pharmacy_0538", "aed_00001", "tourist_info_08")

find_nearby

Find the nearest facilities to a GPS point, sorted by distance. The right default for "nearest", "closest", or "around here" — and for urgent needs.

Parameters:

• lat (required): Latitude (Busan spans ~35.04 to ~35.40)
• lng (required): Longitude (Busan spans ~128.78 to ~129.30)
• radius_m (optional): Search radius in meters, 100-5000 (default: 500). Widen it if the first call comes back empty — 500m is dense downtown but sparse in outer districts.
• type (optional): Restrict to one facility type. Omit to get whatever is closest.
• limit (optional): Max results, 1-20 (default: 5)

Each result includes distance_m, the straight-line distance from the search point.

get_subway_timetable

Not available yet. No timetable data is loaded, so every call returns nothing for every station. The tool stays registered so it starts working the moment the data lands — see Known Data Limitations.

submit_feedback

Report missing, wrong, or stale data. Reports are read and acted on: earlier reports about empty English fields led to all 8,680 records being filled.

Parameters:

• category (required): new_data | data_quality | coverage | format | frequency | other
• message (required): What's wrong. Include the place ID when you have one.
• priority (optional): low | medium | high (default: medium)

Quick Start

Option A: Smithery (Recommended)

Visit Busan Essentials on Smithery and follow the setup instructions for your MCP client.

Option B: Direct Connection

Add to your MCP client config (e.g., Claude Desktop claude_desktop_config.json):

{
  "mcpServers": {
    "busan-essentials": {
      "url": "https://busan-essentials-mcp-85013349489.asia-northeast3.run.app/mcp"
    }
  }
}

Option C: Run Locally

git clone https://github.com/do-droid/busan-essentials.git
cd busan-essentials
API_BASE_URL="https://asia-northeast3-busan-essentials.cloudfunctions.net/api" \
uv run python -m src.server

Example Queries

An AI agent can use these tools to answer questions like:

English

• "Find a pharmacy near Seomyeon Station"
• "Where is the nearest public restroom to Haeundae Beach?"
• "I need a wheelchair-accessible restroom in Haeundae that's open 24 hours"
• "Find free WiFi hotspots in Gwangalli area"
• "Where is the closest AED to Nampo-dong?"
• "Which tourist information center near me has English-speaking staff?"

日本語

• 「西面（ソミョン）で薬局を探して」
• 「広安里（クァンアルリ）の近くで無料Wi-Fiが使える場所は？」
• 「海雲台（ヘウンデ）駅周辺の公衆トイレを教えて」

中文

• "在西面附近找药店"
• "广安里附近哪里有免费WiFi？"
• "南浦洞附近最近的AED在哪里？"

Feedback

We actively review and incorporate feedback to improve data quality and coverage.

For AI agents: Use the submit_feedback tool during a conversation to report issues or suggest improvements.

For developers: Open a feedback issue on GitHub.

Categories: new_data | data_quality | coverage | format | frequency | other

Known Data Limitations

• subway: Not loaded. The Humetro timetable API (data.go.kr 15000522) requires a separate usage application that is still pending, so get_subway_timetable returns nothing for every station. The parser and config are in place; the data flows the moment the key is approved. Donghae Line and Busan–Gimhae Light Rail follow later.
• pharmacy: No 24-hour or foreign-language flags. The nationwide E-Gen source does not carry them, so is_24h reads false on all 1,667 records — that is a source gap, not a statement that no 24-hour pharmacy exists in Busan.
• toilet coordinates fall back to the district centroid; the upstream standard dataset dropped its WGS84 columns. wifi, pharmacy, aed, and tourist_info have precise coordinates.
• English names and addresses are generated by Revised Romanization plus a facility-type glossary (미래약국 → "Mirae Pharmacy"). Loanword names romanize phonetically rather than recovering the original spelling (오션약국 → "Osyeon Pharmacy", not "Ocean"). Korean fields are always the authoritative ones.
• tourist_info is 25 records, not 26: the source dataset contains a test entry ("테스트 관광안내소") which is excluded.

Data Sources

All data sourced from official Korean government open data, used under KOGL Type 1 (출처표시 / Attribution):

• Korea Open Data Portal (data.go.kr)
• Busan Open Data Portal (data.busan.go.kr)

License

• Code — MIT, see LICENSE.
• Data — KOGL Type 1 (공공누리 제1유형 · Attribution), see NOTICE. Commercial use and modification are permitted; the originating portal must be credited.