Cal.com FastMCP 服务器

⚠️ 免责声明：本项目与 Cal.com 无关，也未得到 Cal.com 的认可。我是一位独立开发者，并无任何官方身份与 Cal.com 相关。

该项目提供了一个 FastMCP 服务器，用于与 Cal.com API 进行交互。它允许语言学习模型（LLMs）使用工具连接到 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 未设置，则会显示警告信息。

可用工具

当前服务器提供了以下工具供 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(...)：列出所有对已认证账户配置的 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-api-version: 2024-08-13 头部，这是根据 Cal.com API v2 文档中该端点的规定。
• API 调用中包含了错误处理，以提供详细的响应信息。

🚀 使用构建

重要安全提示

切勿直接将您的 CALCOM_API_KEY 硬编码到源代码中。 总是按照安装说明使用环境变量来确保您的 API 密钥安全。