예약 플랫폼 통합 관리 MCP

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

주요 기능

📊 예약 조회

• 오늘/특정 날짜 예약 현황 조회
• 플랫폼별 예약 조회
• 예약 검색

⚠️ 중복 예약 방지

• 중복 예약 자동 감지
• 예약 가능 시간대 조회

💰 매출/정산 관리

• 일/주/월 매출 요약
• 플랫폼별 매출 분석
• 플랫폼 수수료 계산

👥 고객 관리

• 블랙리스트 관리
• 노쇼 고객 추적
• 고객 예약 이력

📝 메시지 생성

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

지원 플랫폼

• 네이버 예약
• 에어비앤비
• 스페이스클라우드
• 야놀자
• 카카오 예약

기술 스택

• Python 3.12+
• FastMCP
• iCalendar (ics) 파싱

설치 방법

# 가상환경 생성
python3 -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# 의존성 설치
pip install -r requirements.txt

사용 방법

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 서버 테스트

개발 로드맵

• [x] 프로젝트 초기 설정
• [x] 데이터 모델 및 저장소
• [x] iCal 파싱 기능
• [x] 예약 조회 Tools (4개)
• [x] 중복 체크 Tools (2개)
• [x] 매출/정산 Tools (2개)
• [x] 고객 관리 Tools (3개)
• [x] 메시지 생성 & 동기화 Tools (2개)
• [x] 로컬 테스트 완료
• [x] 데이터 관리 개선 (인메모리 캐시)
• [x] Remote HTTP 서버 전환
• [x] 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 등록

1. https://playmcp.kakao.com/console 접속
2. 배포된 서버 URL 등록
3. Tools 정보 입력
4. 심사 제출 → 전체 공개
5. 공모전 응모

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

성능 개선

인메모리 캐시

• 모든 데이터를 메모리에 로드하여 읽기 성능 대폭 향상
• Thread Lock으로 동시성 문제 해결
• 파일 I/O 최소화

라이선스

MIT License