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 密钥的安全。