VisitKorea Wellness Tourism MCP Server
!Python !MCP !Transport 
An MCP (Model Context Protocol) server that wraps the Korea Tourism Organization (KTO) Wellness Tourism Open API (WellnessTursmService), exposing 9 structured tools that AI agents — including Claude, Manus AI, and any MCP-compatible client — can call directly via Streamable HTTP. Supports 7 wellness themes and 9 languages.
Live endpoint: https://<your-replit-url>/mcp
---
Features
- Area-based search — list wellness tourism spots by province, city, or district
- Location-based search — find spots within a GPS radius (up to 20 km), with distance sorting
- Keyword search — full-text search in Korean, English, and other languages
- 7 wellness theme filters — Hot spring/Spa, Jjimjilbang, Traditional medicine, Healing meditation, Beauty spa, Nature healing, Other wellness
- Multilingual support — 9 languages: Korean, English, Japanese, Simplified/Traditional Chinese, German, French, Spanish, Russian
- Sync list — full dataset synchronisation list for building and maintaining local databases
- Detail records — common info, intro info (type-specific), repeating structured info, and image galleries
- 9 MCP tools — one per API operation, with full parameter documentation in docstrings
- Stateless transport — every request is self-contained; no session state, no expiry issues
- Security hardened — rate limiting (60 req/min per IP), security headers (CSP, X-Frame-Options), API key log redaction
---
Prerequisites
- Python 3.11+
- A KTO Open API key from data.go.kr (Service ID:
15144030)
---
Installation & Setup
1. Clone the repository
git clone https://github.com/leejaew/visitkorea-wellnesstourism-mcp.git
cd visitkorea-wellnesstourism-mcp2. Install dependencies
pip install -r requirements.txt3. Obtain your API key
- Visit https://www.data.go.kr/data/15144030/openapi.do
- Sign in or create a 공공데이터포털 account
- Click 활용신청 (Request API access) for the
WellnessTursmService - After approval (~10 minutes), go to My Page and copy your 일반 인증키 (Encoding) key
4. Set the environment variable
export WELLNESS_API_KEY_ENCODING="your_url_encoded_key_here"On Replit, add it to Secrets (not environment variables) under the key name WELLNESS_API_KEY_ENCODING.
The key from data.go.kr is already URL-encoded (contains
%2B,%2F, etc.). Use that value as-is — do not decode or re-encode it.
5. Run the server
cd artifacts/wellness-mcp
python main.pyThe server starts on the port specified by the PORT environment variable (defaults to 8080).
| URL | Purpose | |-----|---------| | http://localhost:8080/ | Developer landing page | | http://localhost:8080/mcp | MCP Streamable HTTP endpoint |
---
Connecting AI Agents
Manus AI
In Manus AI's connector settings, add a custom MCP server:
| Field | Value | |-------|-------| | Type | streamable-http | | URL | https://<your-replit-url>/mcp | | Authentication | None |
Claude Desktop / Other MCP clients
Paste into your client's MCP configuration:
{
"mcpServers": {
"visitkorea-wellnesstourism": {
"type": "streamable-http",
"url": "https://<your-replit-url>/mcp"
}
}
}Replace the URL with your own deployed endpoint if you forked the repository.
---
Tool Reference
Tool 1 — get_legal_district_codes
Retrieve legal administrative district (법정동) codes for province/city and district filtering.
Upstream endpoint: GET /ldongCode
| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | lang_div_cd | string | Optional | Language code (default: KOR) | | num_of_rows | int | Optional | Results per page (default: 10) | | page_no | int | Optional | Page number (default: 1) | | l_dong_regn_cd | string | Optional | Province/city code (e.g. 11 = Seoul). Omit to list all provinces. | | l_dong_list_yn | string | Optional | N = 시도/시군구 codes (default); Y = full 법정동 list |
---
Tool 2 — search_wellness_by_area
List wellness tourism spots filtered by region, content type, and wellness theme.
Upstream endpoint: GET /areaBasedList
| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | lang_div_cd | string | Optional | Language code (default: KOR) | | num_of_rows | int | Optional | Results per page (default: 10) | | page_no | int | Optional | Page number (default: 1) | | arrange | string | Optional | Sort order — A/C/D (no image required); O/Q/R (image required) | | content_type_id | string | Optional | Content type ID (see reference table) | | mdfcn_dt | string | Optional | Modified date filter in YYMMDD format | | l_dong_regn_cd | string | Optional | Province/city code | | l_dong_signgu_cd | string | Optional | District code (requires l_dong_regn_cd) | | wellness_thema_cd | string | Optional | Wellness theme code (see reference table) |
---
Tool 3 — search_wellness_by_location
Find wellness spots within a GPS radius of a point in South Korea, sorted by proximity.
Upstream endpoint: GET /locationBasedList
| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | map_x | float | Required | GPS longitude (WGS84) e.g. 126.9780 | | map_y | float | Required | GPS latitude (WGS84) e.g. 37.5665 | | radius | int | Required | Search radius in metres — maximum 20000 | | lang_div_cd | string | Optional | Language code (default: KOR) | | num_of_rows | int | Optional | Results per page (default: 10) | | arrange | string | Optional | E = nearest first (no image); S = nearest first (image required) | | content_type_id | string | Optional | Content type ID | | wellness_thema_cd | string | Optional | Wellness theme code |
Response includes a dist field on each item showing the distance in metres from the search point.
---
Tool 4 — search_wellness_by_keyword
Full-text keyword search across all wellness tourism content.
Upstream endpoint: GET /searchKeyword
| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | keyword | string | Required | Search term in Korean or English (e.g. "스파", "spa") | | lang_div_cd | string | Optional | Language code (default: KOR) | | num_of_rows | int | Optional | Results per page (default: 10) | | page_no | int | Optional | Page number (default: 1) | | arrange | string | Optional | Sort order | | content_type_id | string | Optional | Content type ID | | l_dong_regn_cd | string | Optional | Province/city code | | wellness_thema_cd | string | Optional | Wellness theme code |
---
Tool 5 — get_wellness_sync_list
Retrieve the full dataset synchronisation list — designed for building and maintaining a local copy of the wellness tourism data.
Upstream endpoint: GET /wellnessTursmSyncList
| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | lang_div_cd | string | Optional | Language code (default: KOR) | | num_of_rows | int | Optional | Results per page (default: 10) | | page_no | int | Optional | Page number (default: 1) | | showflag | string | Optional | 1 = publicly visible records only; 0 = hidden records | | mdfcn_dt | string | Optional | Modified date filter in YYMMDD format | | old_content_id | string | Optional | Delta sync — retrieve records after this content ID | | wellness_thema_cd | string | Optional | Wellness theme code |
Returns the same summary fields as search_wellness_by_area, plus showflag and oldContentId.
---
Tool 6 — get_wellness_common_info
Fetch the complete common detail record for a single venue: title, address, GPS, phone, overview, homepage, copyright type.
Upstream endpoint: GET /detailCommon
| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | content_id | string | Required | Content ID from a search result (e.g. "702551") | | lang_div_cd | string | Optional | Language code (default: KOR) | | num_of_rows | int | Optional | Results per page (default: 10) | | page_no | int | Optional | Page number (default: 1) |
The
homepagefield may contain raw HTML anchor tags — extract the URL before displaying.
---
Tool 7 — get_wellness_intro_info
Fetch type-specific introductory details (hours, parking, rest days, capacity, credit card info). Response fields vary by content_type_id.
Upstream endpoint: GET /detailIntro
| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | content_id | string | Required | Content ID | | content_type_id | string | Required | Must match the contentTypeId from the search result | | lang_div_cd | string | Optional | Language code (default: KOR) | | num_of_rows | int | Optional | Results per page (default: 10) | | page_no | int | Optional | Page number (default: 1) |
For tourist attractions (type 12 / 76) returns: accomcount, chkcreditcard, expagerange, expguide, infocenter, opendate, parking, restdate, useseason, usetime.
---
Tool 8 — get_wellness_repeating_info
Fetch repeating structured info items: entrance fees, facilities, amenities, accessibility features, reservation guidance.
Upstream endpoint: GET /detailInfo
| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | content_id | string | Required | Content ID | | content_type_id | string | Required | Must match the venue's category | | lang_div_cd | string | Optional | Language code (default: KOR) | | num_of_rows | int | Optional | Results per page (default: 10) | | page_no | int | Optional | Page number (default: 1) |
Returns a list of items each with infoname, infotext, serialnum, fldgubun. Note: this endpoint returns contentid and contenttypeid in lowercase (unlike other endpoints which use camelCase).
---
Tool 9 — get_wellness_images
Retrieve all image URLs and copyright types for a specific venue.
Upstream endpoint: GET /detailImage
| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | content_id | string | Required | Content ID | | lang_div_cd | string | Optional | Language code (default: KOR) | | num_of_rows | int | Optional | Results per page (default: 10) | | page_no | int | Optional | Page number (default: 1) | | image_yn | string | Optional | Y = venue photos (default); N = food/menu images (restaurants only) |
Returns per image: orgImage (~500×333 px), thumbImage (~150×100 px), cpyrhtDivCd, imgname, serialnum.
---
Reference Tables
Wellness Theme Codes
| Code | English | Korean | |------|---------|--------| | EX050100 | Hot spring / Sauna / Spa | 온천/사우나/스파 | | EX050200 | Jjimjilbang (Korean sauna) | 찜질방 | | EX050300 | Korean traditional medicine | 한방 체험 | | EX050400 | Healing meditation | 힐링 명상 | | EX050500 | Beauty spa | 뷰티 스파 | | EX050600 | Other wellness | 기타 웰니스 | | EX050700 | Nature healing | 자연 치유 |
Language Codes
| Code | Language | |------|----------| | KOR | Korean (한국어) — default; most complete dataset | | ENG | English | | JPN | Japanese (日本語) | | CHS | Chinese Simplified (简体中文) | | CHT | Chinese Traditional (繁體中文) | | GER | German (Deutsch) | | FRE | French (Français) | | SPN | Spanish (Español) | | RUS | Russian (Русский) |
Content Type IDs
content_type_id values differ between Korean and multilingual responses.
| Category | Korean (KOR) | Multilingual (ENG, JPN, etc.) | |----------|---------------|----------------------------------| | Tourist attraction | 12 | 76 | | Cultural facility | 14 | 78 | | Event / festival | 15 | 85 | | Leisure sports | 28 | 75 | | Accommodation | 32 | 80 | | Shopping | 38 | 79 | | Restaurant | 39 | 82 | | Travel course | 25 | Korean only | | Transport | Korean only | 77 |
Most wellness venues are classified as tourist attraction (12 for Korean, 76 for multilingual).
Province Codes (common)
| Code | Region | |------|--------| | 11 | Seoul (서울) | | 21 | Busan (부산) | | 22 | Daegu (대구) | | 23 | Incheon (인천) | | 31 | Gyeonggi-do (경기) | | 32 | Gangwon-do (강원) | | 37 | Gyeongsangbuk-do (경북) | | 38 | Gyeongsangnam-do (경남) | | 39 | Jeju Island (제주) |
Use get_legal_district_codes() (no parameters) to retrieve all 17 province codes, or pass a province code to get its district (시군구) codes.
---
Usage Examples
Find hot spring spas near Busan Station
search_wellness_by_location(
map_x=129.0319, map_y=35.1148,
radius=5000,
wellness_thema_cd="EX050100",
arrange="E",
lang_div_cd="ENG"
)Search for spas in Seoul (English)
search_wellness_by_area(
l_dong_regn_cd="11",
wellness_thema_cd="EX050100",
lang_div_cd="ENG",
num_of_rows=10
)Keyword search
search_wellness_by_keyword(keyword="스파", lang_div_cd="KOR", num_of_rows=5)
search_wellness_by_keyword(keyword="spa", lang_div_cd="ENG", num_of_rows=5)Full venue detail retrieval
# 1. Get common info (address, overview, GPS, phone)
get_wellness_common_info(content_id="702551", lang_div_cd="ENG")
# 2. Get operational details (hours, parking, rest days)
get_wellness_intro_info(content_id="702551", content_type_id="76", lang_div_cd="ENG")
# 3. Get fees and facilities
get_wellness_repeating_info(content_id="702551", content_type_id="76", lang_div_cd="ENG")
# 4. Get photos
get_wellness_images(content_id="702551", lang_div_cd="ENG")---
Project Structure
artifacts/wellness-mcp/
├── main.py # Replit entrypoint — Starlette app, rate limiting, security headers, lifespan
├── server.py # FastMCP server definition with 9 registered tool wrappers
├── api/
│ ├── __init__.py # Re-exports WellnessClient, WellnessAPIError
│ ├── config.py # BASE_URL, HTTP timeout constants, shared httpx client factory
│ ├── cache.py # TTL response cache with per-key stampede locks
│ ├── validation.py # Allowed-value sets and parameter guard functions
│ ├── parser.py # WellnessAPIError, JSON/XML response normaliser
│ └── client.py # WellnessClient — async httpx client with 9 API methods
├── tools/
│ ├── __init__.py # Re-exports all 9 tool functions
│ ├── catalog.py # get_legal_district_codes, get_wellness_sync_list
│ ├── search.py # search_wellness_by_area/location/keyword
│ └── detail.py # get_wellness_common/intro/repeating_info, get_wellness_images
├── static/
│ ├── index.html # Developer landing page
│ └── favicon.png # Server icon
├── requirements.txt
├── MANUS_INSTRUCTIONS.md # Detailed usage guide for Manus AI agents
├── README.md
└── LICENSE---
Dependencies
mcp[cli]>=1.0.0 # MCP SDK (tested with 1.27.0)
httpx>=0.27.0 # Async HTTP client for upstream API calls (tested with 0.28.1)
starlette>=0.37.0 # ASGI framework for routing and middleware (tested with 1.0.0)
uvicorn>=0.29.0 # ASGI server (tested with 0.44.0)
uvloop>=0.19.0 # Optional: faster event loop (tested with 0.22.1; falls back gracefully)---
Transport & Protocol Notes
This server uses MCP Streamable HTTP transport with two non-default settings:
| Setting | Value | Reason | |---------|-------|--------| | json_response | True | Clients such as Manus AI send Accept: application/json only. SSE/streaming mode requires both application/json and text/event-stream in the Accept header and returns HTTP 406 otherwise. JSON mode removes this requirement. | | stateless_http | True | Gateway-style clients enumerate tools at connector setup time and execute tool calls much later. Stateful sessions are lost whenever the server restarts, causing "Session not found" errors. Stateless mode makes every request fully self-contained — no session IDs are issued or required. |
The server is compatible with any MCP 2025-03-26 client that sends Accept: application/json.
---
Security
| Feature | Details | |---------|---------| | Rate limiting | 60 requests per 60 seconds per IP on /mcp; returns HTTP 429 with Retry-After | | Security headers | Content-Security-Policy, X-Content-Type-Options, X-Frame-Options, Referrer-Policy | | API key redaction | serviceKey= is replaced with [REDACTED] in all uvicorn access and error logs | | Cache stampede protection | Per-key asyncio.Lock prevents multiple concurrent upstream calls for the same request |
---
Important Usage Notes
| Note | Detail | |------|--------| | content_type_id differs by language | Tourist attractions are 12 for KOR but 76 for ENG/JPN/etc. Using the wrong ID returns empty results, not an error. | | GPS radius hard limit | radius for search_wellness_by_location must not exceed 20000 metres. | | District code dependency | l_dong_signgu_cd is ignored by the API unless l_dong_regn_cd is also provided. | | content_type_id is required | Both get_wellness_intro_info and get_wellness_repeating_info require content_type_id. Always read it from the search result and pass it through. | | Homepage field may contain HTML | The homepage field from get_wellness_common_info sometimes contains raw <a href="..."> tags. Extract the URL before displaying. | | Korean data is most complete | Multilingual datasets may have fewer records or missing fields. If English returns no results, retry with lang_div_cd="KOR". | | Pagination | Default num_of_rows is 10. Increase to 50–100 for broader searches. Use totalCount with pageNo to traverse multiple pages. |
---
Contributing
Contributions are welcome. Please open an issue before submitting a pull request. Ensure all changes are tested against the live API and that no API keys are committed to the repository.
---
License
MIT License — © 2026 leejaew. See LICENSE for full text.
Tourism data provided by the Korea Tourism Organization (KTO) via the 공공데이터포털 open API platform. Data usage is subject to KTO terms — attribution is required for Type1 content; Type3 content additionally prohibits modification.
