예약 플랫폼 통합 관리 MCP
여러 예약 플랫폼(네이버, 에어비앤비, 스페이스클라우드, 야놀자, 카카오)의 실제 예약 데이터를 iCal 표준을 통해 한 곳에서 통합 관리하는 MCP 서버입니다.
✨ 실제 플랫폼 연동
이 MCP 서버는 실제 예약 플랫폼과 연동됩니다:
- 각 플랫폼에서 제공하는 iCal URL을 통해 실시간 예약 데이터 동기화
- 서버 시작 시 자동으로 모든 플랫폼 예약 가져오기
- 1시간마다 자동 동기화 (설정 가능)
- 수동 동기화 Tool 제공
iCal URL 설정 방법: ICAL_SETUP_GUIDE.md 참고
주요 기능
📊 예약 조회
- 오늘/특정 날짜 예약 현황 조회
- 플랫폼별 예약 조회
- 예약 검색
⚠️ 중복 예약 방지
- 중복 예약 자동 감지
- 예약 가능 시간대 조회
💰 매출/정산 관리
- 일/주/월 매출 요약
- 플랫폼별 매출 분석
- 플랫폼 수수료 계산
👥 고객 관리
- 블랙리스트 관리
- 노쇼 고객 추적
- 고객 예약 이력
📝 메시지 생성
- 예약 안내 메시지 자동 생성
지원 플랫폼
- 네이버 예약
- 에어비앤비
- 스페이스클라우드
- 야놀자
- 카카오 예약
기술 스택
- Python 3.12+
- FastMCP
- iCalendar (ics) 파싱
설치 방법
# 가상환경 생성
python3 -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
# 의존성 설치
pip install -r requirements.txt
🚀 빠른 시작 (실제 플랫폼 연동)
1. 환경 변수 설정
# .env 파일 생성
cp .env.example .env
# .env 파일 편집
nano .env # 또는 원하는 에디터 사용
각 플랫폼의 iCal URL을 입력하세요:
# 플랫폼 iCal URLs (실제 URL로 변경)
AIRBNB_ICAL_URL=https://www.airbnb.com/calendar/ical/12345678.ics?s=your-secret-key
SPACECLOUD_ICAL_URL=https://www.spacecloud.kr/calendar/ical/your-space-id
NAVER_ICAL_URL=https://booking.naver.com/booking/ical/your-store-id.ics
# ... 기타 플랫폼
📖 각 플랫폼에서 iCal URL 얻는 방법:
- 자세한 가이드: ICAL_SETUP_GUIDE.md
- 에어비앤비: 호스팅 → 캘린더 → 캘린더 내보내기
- 네이버: 예약 관리 → 캘린더 설정 → iCal 내보내기
- 각 플랫폼 고객센터 문의 가능
2. 서버 실행
# HTTP 모드로 서버 시작
TRANSPORT=http python -m src.server
서버가 시작되면 자동으로 모든 플랫폼의 예약을 동기화합니다!
🔄 Syncing airbnb...
✅ airbnb: 12건 동기화 완료
🔄 Syncing naver...
✅ naver: 5건 동기화 완료
✅ 총 2개 플랫폼에서 17건의 예약을 동기화했습니다.
테스트 (샘플 데이터)
실제 플랫폼 연동 없이 테스트하려면:
1. 테스트 데이터 생성
# 가상환경 활성화
source venv/bin/activate
# 샘플 데이터 생성
python test_data.py
2. MCP 서버 테스트
# MCP 서버 테스트 실행
python test_mcp.py
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
설정 예시:
{
"mcpServers": {
"reservation-platform": {
"command": "python",
"args": ["-m", "src.server"],
"cwd": "/path/to/PlayMCP",
"env": {
"PATH": "/path/to/PlayMCP/venv/bin:${PATH}"
}
}
}
}
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에서 예약 동기화 ⭐
프로젝트 구조
PlayMCP/
├── src/
│ ├── server.py # MCP 서버 메인
│ ├── models.py # 데이터 모델
│ ├── storage.py # 데이터 저장소
│ ├── ical_parser.py # iCal 파싱
│ └── tools/ # MCP Tools
├── data/ # 로컬 데이터 저장
├── requirements.txt # Python 의존성
├── test_data.py # 테스트 데이터 생성
└── test_mcp.py # MCP 서버 테스트
개발 로드맵
- 프로젝트 초기 설정
- 데이터 모델 및 저장소
- iCal 파싱 기능
- 예약 조회 Tools (4개)
- 중복 체크 Tools (2개)
- 매출/정산 Tools (2개)
- 고객 관리 Tools (3개)
- 메시지 생성 & 동기화 Tools (2개)
- 로컬 테스트 완료
- 데이터 관리 개선 (인메모리 캐시)
- Remote HTTP 서버 전환
- Docker 설정 완료
- 클라우드 배포 (Google Cloud Run/Railway/Render)
- PlayMCP 등록
로컬 실행
STDIO 모드 (Claude Desktop/CLI)
python3 -m src.server
HTTP 모드 (Remote MCP 서버)
# HTTP transport로 실행
TRANSPORT=http PORT=8000 python3 -m src.server
서버는 http://localhost:8000/mcp에서 접근 가능합니다.
Docker 배포
Docker로 실행
# 이미지 빌드
docker build -t reservation-mcp-server .
# 컨테이너 실행
docker run -p 8000:8000 -e TRANSPORT=http reservation-mcp-server
Docker Compose로 실행
docker-compose up -d
클라우드 배포
자세한 배포 방법은 DEPLOYMENT.md를 참고하세요.
- Google Cloud Run: 완전 관리형 컨테이너 플랫폼
- Railway: 간편한 Git 기반 배포
- Render: 무료 티어 지원
PlayMCP 등록
- https://playmcp.kakao.com/console 접속
- 배포된 서버 URL 등록
- Tools 정보 입력
- 심사 제출 → 전체 공개
- 공모전 응모
자세한 내용은 DEPLOYMENT.md의 "PlayMCP 등록" 섹션 참고
🔄 자동 동기화 설정
서버는 환경 변수에 설정된 iCal URL을 주기적으로 확인하여 자동으로 예약을 업데이트합니다.
동기화 주기 조정
.env 파일에서 설정:
ICAL_SYNC_ENABLED=true # 자동 동기화 활성화
ICAL_SYNC_INTERVAL=3600 # 1시간마다 동기화 (초 단위)
권장 설정:
- 예약이 많은 경우: 1시간 (3600초)
- 예약이 적은 경우: 2-4시간 (7200-14400초)
성능 개선
인메모리 캐시
- 모든 데이터를 메모리에 로드하여 읽기 성능 대폭 향상
- Thread Lock으로 동시성 문제 해결
- 파일 I/O 최소화
스마트 동기화
- 플랫폼별 예약을 완전히 교체하여 중복 방지
- 변경된 예약만 업데이트하여 효율성 향상
라이선스
MIT License
