개발자 가이드 · K-STAY MCP & API | K-STAY · 한국 숙소 종합 AI 비서

🚀 5분 빠른 시작 — Claude Desktop에 연결

아직 사용해본 적 없어도 괜찮습니다. 4단계만 따라하세요.

Node.js 설치

한 번만. macOS는 brew install node, Windows는 nodejs.org에서 LTS.

node --version

K-STAY 클론·빌드

로컬에 설치 (npm publish 후엔 생략 가능).

git clone https://github.com/josanku/wehome-insight.git ~/k-stay
cd ~/k-stay/mcp-server
npm install && npm run build

Claude 설정에 추가

~/Library/Application Support/Claude/claude_desktop_config.json (macOS) 편집.

{"mcpServers":{"k-stay":{
 "command":"node",
 "args":["~/k-stay/mcp-server/dist/index.js"]
}}}

재시작 → 사용

Cmd+Q로 완전 종료 후 다시 실행. 🔌 아이콘 확인.

"10월 한국 축제 알려줘"

🎯 MCP가 뭐고 왜 쓰나?

MCP (Model Context Protocol)는 Anthropic이 2024년 11월 공개한 오픈 표준입니다. LLM이 외부 데이터·도구를 native 함수처럼 호출하게 해줍니다.

❌ MCP 없이 (WebFetch)

사용자: "한옥체험업 통계 줘"
Claude: WebFetch로 URL 수동 입력
→ 응답 파싱
→ 매번 URL 기억해야 함
→ 느림 (2-3초)

✅ MCP 있을 때

사용자: "한옥체험업 통계 줘"
Claude: get_hanok_stats() 자동 호출
→ 결과를 바로 분석
→ URL·인자·파싱 모두 자동
→ 빠름 (0.5초)

💬 실제 사용 시나리오 7가지

실제로 어떻게 쓰는지가 가장 중요합니다. 자연어로 물어보면 Claude가 알아서 도구를 호출합니다.

🧳 시나리오 1 · 여행자

한국 갈건데, 10월 외국인 추천 축제 + 근처 한옥숙박

"10월에 한국 갈건데, 외국인이 좋아할 만한 축제 3개랑 그 근처 한옥숙박 추천해줘"

→ Claude가 자동으로 get_festivals(month=10) 호출
→ 진주남강유등·안동탈춤·부산국제영화제 발견
→ 각 축제 인근 search_hanok_listings(sido=...) 호출
→ 통합 답변 생성

진주남강유등(10/1-15, 280만명) → 진주 한옥체험관 / 안동탈춤(9/26-10/5) → 하회마을 충효당·양진당 / 부산국제영화제(10/2-11) → 광안리 호텔

🏠 시나리오 2 · 예비 공유숙박 호스트

내 동네 시장 분석

"마포구에서 외도민업 시작하려는데, 현재 영업중 호스트가 몇 명이고 신규 등록 추이는?"

→ get_stats(sido='서울특별시') + get_registrations_monthly(year='2026')
→ 마포구 1,752곳·월 60건 신규
→ 시장 포화도 + 트렌드 분석

마포구 1,752곳 영업중 (전국 17.6%) · 월평균 신규 60건. 지속 성장세 — 입지 좋으면 진입 가능.

📊 시나리오 3 · 데이터 저널리스트

코로나 이전 대비 회복률 국가별 분석

"코로나 이전(2019)과 비교해서 외국인 관광객 회복률을 국가별로 분석해줘"

→ get_inbound_tourism()
→ 2019-2025 연간 + 국가별 yoy
→ 회복률 = 2025/2019 계산

중국 78%·일본 105%·베트남 113%·미국 124%·인도 129%. 동남아·서구권 완전 회복, 중국만 정체.

🏯 시나리오 4 · 한옥 마니아

보물 등급 종택 + 종부 운영

"보물로 지정된 한옥 종택만 알려줘. 종부가 직접 운영하는 곳 우선"

→ get_meongpum_gotaek()
→ cultural_property에 '보물' 필터
→ experiences에 '종부 이야기' 우선 정렬

임청각(보물 182호)·양진당(306호)·향단(412호)·관가정(442호)·운조루(국가민속8호)

🎤 시나리오 5 · K-Pop 팬 (외국인)

BTS 팬 서울 투어

"I'm a BTS fan visiting Seoul. Where should I go?"

→ get_kculture_hotspots()
→ category='k-pop' + fandom='ARMY' 필터
→ 동선 추천

HYBE 사옥(용산)·SMTOWN coexartium(강남)·BTS 마이크드롭 신촌·BTS 인더숲(제주)

💻 시나리오 6 · 개발자

Next.js + 카카오맵 한옥 지도

"Next.js 프로젝트에서 한옥 지도 만들고 싶어. API 호출 코드 짜줘"

→ get_hanok_villages() 데이터 구조 파악
→ search_hanok_listings(limit=500) 좌표 확인
→ Next.js + Kakao Maps 통합 코드 생성

완성된 React 컴포넌트(서버 컴포넌트 + 클라이언트 맵) + tailwind 스타일 + 카카오 SDK 로딩 코드 일체 제공

📚 시나리오 7 · 연구자

학술 논문용 데이터셋

"한옥체험업의 연도별 등록 추이를 그래프로 그릴 수 있는 데이터 줘"

→ get_hanok_stats() by_year 필드
→ CSV·Python pandas/matplotlib 코드
→ 학술 인용 형식 제공

2018: 1,452 → 2026: 2,522곳. 인용: "Data from K-STAY (k-stay.ai) · 행정안전부 인허가, 2026"

🛠️ 16개 도구 한눈에

자연어로 물으면 Claude가 알아서 호출합니다. 직접 호출도 가능.

get_stats

외도민업 종합 통계 · sido/category 필터

get_categories_overview

5종 카테고리 요약

get_registrations_monthly

지역별 월간 신규 등록

get_hanok_stats

한옥체험업 (2,522곳)

search_hanok_listings

한옥 영업장 검색 (좌표 포함)

get_hanok_villages

한옥마을 51곳

get_meongpum_gotaek

KTO 명품고택 55곳

get_temple_stays

템플스테이 사찰 130+

search_lodging

호텔/호스텔/농어촌/펜션 검색

get_lodging_stats

카테고리별 통계

get_inbound_tourism

외국인 관광객 (월·국가·연령)

get_kculture_hotspots

K-Pop·Drama·Food·Beauty 35곳

get_korea100

한국관광 100선 (연도별)

get_festivals

전국 축제 44개 · 월 필터

get_data_sources

데이터 출처 카탈로그

get_monthly_report

월간 시장 리포트

📦 다른 도구 연결 (Cursor·Continue·Cline)

Cursor

Settings → Features → MCP Servers → Add new server:

name: k-stay
type: command
command: node /path/to/mcp-server/dist/index.js

Claude Code (CLI)

claude mcp add k-stay -- node /path/to/mcp-server/dist/index.js
claude
> /mcp     # 등록된 MCP 도구 목록 확인
> 서울 한옥 5개 추천해줘

Cline (VS Code)

.vscode/cline_mcp_settings.json:
{
  "mcpServers": {
    "k-stay": {
      "command": "node",
      "args": ["/path/to/mcp-server/dist/index.js"]
    }
  }
}

🔧 트러블슈팅

Claude Desktop에 🔌 아이콘이 안 보임 → 설정 파일 JSON 문법 확인(jsonlint.com), Cmd+Q로 완전 종료 후 재시작, 로그 확인 ~/Library/Logs/Claude/mcp*.log
"Cannot find module" 오류 → cd mcp-server && npm install && npm run build 재실행
Korean 응답이 깨짐 → 터미널 export LANG=ko_KR.UTF-8
API가 느림 → 첫 호출 cold start, 이후 5분 캐시
데이터가 오래됨 → 매일 04:00 KST 자동 갱신, 즉시 확인: get_data_sources

K-STAY를 당신의 AI에 연결

🚀 5분 빠른 시작 — Claude Desktop에 연결

🎯 MCP가 뭐고 왜 쓰나?

❌ MCP 없이 (WebFetch)

✅ MCP 있을 때

💬 실제 사용 시나리오 7가지

한국 갈건데, 10월 외국인 추천 축제 + 근처 한옥숙박

내 동네 시장 분석

코로나 이전 대비 회복률 국가별 분석

보물 등급 종택 + 종부 운영

BTS 팬 서울 투어

Next.js + 카카오맵 한옥 지도

학술 논문용 데이터셋

🛠️ 16개 도구 한눈에

📦 다른 도구 연결 (Cursor·Continue·Cline)

Cursor

Claude Code (CLI)

Cline (VS Code)

🔧 트러블슈팅

📚 더 깊이 알아보기

K-STAY를 당신의 AI에 연결

🚀 5분 빠른 시작 — Claude Desktop에 연결

🎯 MCP가 뭐고 왜 쓰나?

❌ MCP 없이 (WebFetch)

✅ MCP 있을 때

💬 실제 사용 시나리오 7가지

한국 갈건데, 10월 외국인 추천 축제 + 근처 한옥숙박

내 동네 시장 분석

코로나 이전 대비 회복률 국가별 분석

보물 등급 종택 + 종부 운영

BTS 팬 서울 투어

Next.js + 카카오맵 한옥 지도

학술 논문용 데이터셋

🛠️ 16개 도구 한눈에

📦 다른 도구 연결 (Cursor·Continue·Cline)

Cursor

Claude Code (CLI)

Cline (VS Code)

📣 K-STAY MCP를 알리는 데 도움을 주세요

🔧 트러블슈팅

📚 더 깊이 알아보기