예약 플랫폼 통합 관리 MCP

여러 예약 플랫폼(네이버, 에어비앤비, 스페이스클라우드, 야놀자, 카카오)의 실제 예약 데이터를 iCal 표준을 통해 한 곳에서 통합 관리하는 MCP 서버입니다.

✨ 실제 플랫폼 연동

이 MCP 서버는 실제 예약 플랫폼과 연동됩니다:

• 각 플랫폼에서 제공하는 iCal URL을 통해 실시간 예약 데이터 동기화

• 서버 시작 시 자동으로 모든 플랫폼 예약 가져오기

• 1시간마다 자동 동기화 (설정 가능)

• 수동 동기화 Tool 제공

iCal URL 설정 방법: ICAL_SETUP_GUIDE.md 참고

주요 기능

📊 예약 조회

• 오늘/특정 날짜 예약 현황 조회

• 플랫폼별 예약 조회

• 예약 검색

⚠️ 중복 예약 방지

• 중복 예약 자동 감지

• 예약 가능 시간대 조회

💰 매출/정산 관리

• 일/주/월 매출 요약

• 플랫폼별 매출 분석

• 플랫폼 수수료 계산

👥 고객 관리

• 블랙리스트 관리

• 노쇼 고객 추적

• 고객 예약 이력

📝 메시지 생성

• 예약 안내 메시지 자동 생성

지원 플랫폼

• 네이버 예약

• 에어비앤비

• 스페이스클라우드

• 야놀자

• 카카오 예약

기술 스택

• Python 3.12+

• FastMCP

• iCalendar (ics) 파싱

설치 방법

🚀 빠른 시작 (실제 플랫폼 연동)

1. 환경 변수 설정

각 플랫폼의 iCal URL을 입력하세요:

📖 각 플랫폼에서 iCal URL 얻는 방법:

• 자세한 가이드: ICAL_SETUP_GUIDE.md

• 에어비앤비: 호스팅 → 캘린더 → 캘린더 내보내기

• 네이버: 예약 관리 → 캘린더 설정 → iCal 내보내기

• 각 플랫폼 고객센터 문의 가능

2. 서버 실행

서버가 시작되면 자동으로 모든 플랫폼의 예약을 동기화합니다!

테스트 (샘플 데이터)

실제 플랫폼 연동 없이 테스트하려면:

1. 테스트 데이터 생성

2. MCP 서버 테스트

3. Claude Desktop에서 사용

Claude Desktop 설정 파일(claude_desktop_config.json)을 Claude Desktop의 설정 디렉토리에 복사:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

설정 예시:

4. 사용 가능한 Tools

📊 예약 조회

• get_today_reservations - 오늘 예약 현황 조회

• get_reservations_by_date - 특정 날짜 예약 조회

• get_reservations_by_platform - 플랫폼별 예약 조회

• get_week_reservations - 이번 주 예약 조회

⚠️ 중복 예약 방지

• check_duplicate_reservations - 중복 예약 감지

• check_time_slot - 특정 시간대 예약 가능 여부 확인

💰 매출/정산

• get_revenue_summary - 매출 요약 (일/주/월)

• calculate_platform_fees - 플랫폼 수수료 계산

👥 고객 관리

• get_blacklist - 블랙리스트 조회

• add_to_blacklist - 블랙리스트 추가

• get_noshow_customers - 노쇼 고객 조회

📝 기타

• generate_reminder_message - 예약 안내 메시지 생성

• sync_platform_ical - 실시간 iCal URL에서 예약 동기화 ⭐

프로젝트 구조

개발 로드맵

• 프로젝트 초기 설정

• 데이터 모델 및 저장소

• iCal 파싱 기능

• 예약 조회 Tools (4개)

• 중복 체크 Tools (2개)

• 매출/정산 Tools (2개)

• 고객 관리 Tools (3개)

• 메시지 생성 & 동기화 Tools (2개)

• 로컬 테스트 완료

• 데이터 관리 개선 (인메모리 캐시)

• Remote HTTP 서버 전환

• Docker 설정 완료

• 클라우드 배포 (Google Cloud Run/Railway/Render)

• PlayMCP 등록

로컬 실행

STDIO 모드 (Claude Desktop/CLI)

HTTP 모드 (Remote MCP 서버)

서버는 http://localhost:8000/mcp에서 접근 가능합니다.

Docker 배포

Docker로 실행

Docker Compose로 실행

클라우드 배포

자세한 배포 방법은 DEPLOYMENT.md를 참고하세요.

• Google Cloud Run: 완전 관리형 컨테이너 플랫폼

• Railway: 간편한 Git 기반 배포

• Render: 무료 티어 지원

PlayMCP 등록

1. https://playmcp.kakao.com/console 접속

2. 배포된 서버 URL 등록

3. Tools 정보 입력

4. 심사 제출 → 전체 공개

5. 공모전 응모

자세한 내용은 DEPLOYMENT.md의 "PlayMCP 등록" 섹션 참고

🔄 자동 동기화 설정

서버는 환경 변수에 설정된 iCal URL을 주기적으로 확인하여 자동으로 예약을 업데이트합니다.

동기화 주기 조정

.env 파일에서 설정:

권장 설정:

• 예약이 많은 경우: 1시간 (3600초)

• 예약이 적은 경우: 2-4시간 (7200-14400초)

성능 개선

인메모리 캐시

• 모든 데이터를 메모리에 로드하여 읽기 성능 대폭 향상

• Thread Lock으로 동시성 문제 해결

• 파일 I/O 최소화

스마트 동기화

• 플랫폼별 예약을 완전히 교체하여 중복 방지

• 변경된 예약만 업데이트하여 효율성 향상

라이선스

MIT License