calcom-mcp

Cal.com FastMCP 서버

⚠️ 면책 조항 : 이 프로젝트는 Cal.com과 제휴 관계가 아니며 Cal.com의 보증도 받지 않습니다. 저는 독립 개발자이며 Cal.com과 공식적인 어떠한 관계도 없습니다.

이 프로젝트는 Cal.com API와 상호 작용할 수 있는 FastMCP 서버를 제공합니다. 이를 통해 언어 학습 모델(LLM)이 도구를 사용하여 이벤트 유형 및 예약 관리와 같은 중요한 Cal.com 기능에 연결할 수 있습니다.

필수 조건

• 파이썬 3.8 이상
• Cal.com 계정 및 API 키(v2)

설정

1. 저장소를 복제하거나(해당되는 경우) 파일을 다운로드합니다.지엑스피1
2. 가상 환경을 만듭니다(권장):
   python -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate
3. 종속성 설치:
   pip install -r requirements.txt
4. Cal.com API 키 설정: CALCOM_API_KEY 환경 변수를 설정해야 합니다. Cal.com 설정 페이지(일반적으로 개발자 또는 보안 설정 아래)에서 API 키를 가져올 수 있습니다.
   • 리눅스/macOS:
     export CALCOM_API_KEY="your_actual_api_key_here"
     영구적으로 적용하려면 셸 구성 파일(예: .bashrc , .zshrc )에 이 줄을 추가하세요.
   • 윈도우(PowerShell):
     $env:CALCOM_API_KEY="your_actual_api_key_here"
     영구적으로 적용하려면 시스템 속성 > 환경 변수를 통해 설정하면 됩니다.

서버 실행

설정이 완료되면 FastMCP 서버를 실행할 수 있습니다.

서버가 localhost:8010에서 시작되고, 실행 중이라는 출력이 표시됩니다. CALCOM_API_KEY 가 설정되지 않으면 경고가 표시됩니다.

사용 가능한 도구

현재 서버는 LLM 상호작용을 위해 다음과 같은 도구를 제공합니다.

• get_api_status() : Cal.com API 키가 환경에 구성되어 있는지 확인합니다. 상태를 나타내는 문자열을 반환합니다.
• list_event_types() : 인증된 계정에 대한 Cal.com의 모든 이벤트 유형 목록을 가져옵니다. 이벤트 유형 목록 또는 오류 메시지가 포함된 사전을 반환합니다.
• get_bookings(...) : Cal.com에서 예약 목록을 가져옵니다. 선택적 필터(event_type_id, user_id, status, date_from, date_to, limit)를 사용합니다. 예약 목록 또는 오류 메시지가 포함된 사전을 반환합니다.
• create_booking(...) : 특정 이벤트 유형 및 참석자를 대상으로 Cal.com에서 새 예약을 생성합니다. 시작 시간, 참석자 정보, 이벤트 유형 식별자 등의 매개변수가 필요합니다. 예약 정보 또는 오류 메시지가 포함된 사전을 반환합니다.
• list_schedules(...) : 인증된 사용자 또는 특정 사용자/팀이 사용할 수 있는 모든 일정을 나열합니다. 선택 필터: user_id, team_id, limit. 일정 목록 또는 오류 메시지가 포함된 사전을 반환합니다.
• list_teams(...) : 인증된 사용자가 이용할 수 있는 모든 팀을 나열합니다. 선택 필터: limit. 팀 목록 또는 오류 메시지가 포함된 사전을 반환합니다.
• list_users(...) : 인증된 계정에서 사용 가능한 모든 사용자를 나열합니다. 선택 필터: limit. 사용자 목록 또는 오류 메시지가 포함된 사전을 반환합니다.
• list_webhooks(...) : 인증된 계정에 구성된 모든 웹훅을 나열합니다. 선택 필터: limit. 웹훅 목록 또는 오류 메시지가 포함된 사전을 반환합니다.

참고: 모든 도구는 CALCOM_API_KEY 환경 변수를 설정해야 합니다. 설정되지 않으면 도구에서 구조화된 오류 메시지를 반환합니다.

도구 사용 및 오류 처리

• 모든 도구는 API 응답(사전이나 문자열)이나 오류에 대한 세부 정보가 포함된 구조화된 오류 메시지를 반환합니다.
• 오류 메시지에는 오류 유형, HTTP 상태 코드(해당되는 경우), Cal.com API의 응답 텍스트가 포함됩니다.
• 최상의 결과를 얻으려면 반환된 데이터를 사용하기 전에 항상 응답에 error 키가 있는지 확인하세요.
• 이 도구는 견고하게 설계되었으며 성공적이거나 실패한 API 호출에 대한 유익한 피드백을 제공합니다.

개발 노트

• Cal.com API 기본 URL은 https://api.cal.com/v2 로 설정됩니다.
• 인증은 주로 CALCOM_API_KEY 가 포함된 Bearer 토큰을 사용하여 처리됩니다.
• create_booking 도구는 Cal.com API v2 문서에서 해당 엔드포인트에 대해 지정한 대로 cal-api-version: 2024-08-13 헤더를 사용합니다.
• API 호출에는 오류 처리가 포함되어 유익한 응답을 제공합니다.

🚀 ~로 구축됨

중요 보안 참고 사항

CALCOM_API_KEY 소스 코드에 직접 하드코딩하지 마세요. API 키의 보안을 유지하려면 설정 지침에 설명된 대로 항상 환경 변수를 사용하세요.