Calcom MCP

🚀 Cal.com FastMCP 服務器

本項目提供了一個用於與 Cal.com API 交互的 FastMCP 服務器。它允許大語言模型（LLMs）使用工具連接到 Cal.com 的重要功能，如管理活動類型和預訂。

⚠️ 重要提示

本項目與 Cal.com 沒有關聯，也未得到其認可。我是一名獨立開發者，與 Cal.com 沒有任何官方關係。

🚀 快速開始

前提條件

• Python 3.8 及以上版本
• 一個 Cal.com 賬戶和 API 密鑰（v2）

安裝指南

1. 克隆倉庫（如果適用）或下載文件

   git clone https://github.com/Danielpeter-99/calcom-mcp.git
   cd calcom-mcp
   

2. 創建虛擬環境（推薦）

   python -m venv venv
   source venv/bin/activate  # 在 Windows 上：venv\Scripts\activate
   

3. 安裝依賴項

   pip install -r requirements.txt
   

4. 設置 Cal.com API 密鑰 你需要設置 CALCOM_API_KEY 環境變量。你可以從 Cal.com 的設置頁面（通常在開發者或安全設置下）獲取 API 密鑰。

   • Linux/macOS

     export CALCOM_API_KEY="your_actual_api_key_here"
     

     要使其永久生效，請將此命令添加到你的 shell 配置文件中（例如 .bashrc、.zshrc）。

   • Windows（PowerShell）

     $env:CALCOM_API_KEY="your_actual_api_key_here"
     

     要使其永久生效，你可以通過系統屬性 > 環境變量進行設置。

運行服務器

設置完成後，你可以運行 FastMCP 服務器：

fastmcp run app.py --transport sse --port 8010

服務器將在本地主機的 8010 端口啟動，你應該會看到表明服務器正在運行的輸出。如果未設置 CALCOM_API_KEY，將會顯示警告信息。

💻 使用示例

可用工具

服務器目前為大語言模型交互提供以下工具：

• 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(...)：列出為經過身份驗證的賬戶配置的所有 Webhook。可選過濾器：limit。返回一個包含 Webhook 列表或錯誤消息的字典。

注意：所有工具都要求設置 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 密鑰的安全。