JinDaGe - calcom-mcp MCP Details

article

README

本项目提供了一个用于与 Cal.com API 进行交互的 FastMCP 服务器。它允许大语言模型（LLMs）借助工具连接到 Cal.com 的重要功能，例如管理活动类型和预约。

克隆仓库（如果适用）或下载文件

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

创建虚拟环境（推荐）

python -m venv venv
source venv/bin/activate  # 在 Windows 系统中使用：venv\Scripts\activate

安装依赖项
```
pip install -r requirements.txt
```
设置 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 环境变量。如果未设置，工具将返回结构化的错误消息。

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