Highlevel Calendar MCP

高级日历MCP服务器

此MCP（模型上下文协议）服务器允许您的高级语音AI动态查询多个日历，绕过内置预约操作一次只支持一个日历的限制。

✅ 现在使用官方的HighLevelSDK进行可靠的API调用！

问题解决了

HighLevel的语音AI有一个内置的预约操作，但它只允许选择一个日历。如果你有多个医生（例如，10名脊椎指压治疗师提供调整），你不能轻易让来电者选择他们喜欢的医生，然后检查可用性。

此MCP服务器通过以下方式解决了这个问题：

1. 动态获取您所在位置的所有日历
2. 按服务名称搜索日历（例如“调整”、“按摩”）
3. 为特定从业者查找日历
4. 检查多个日历的可用性
5. 在所有相关日历中查找下一个可用时段

运作原理

Caller: "I need to schedule an adjustment"
   ↓
Voice AI calls: search_calendars_by_service("adjustment")
   ↓
MCP returns: List of 10 practitioners who offer adjustments
   ↓
Voice AI: "We have Dr. Smith, Dr. Jones... who would you prefer?"
   ↓
Caller: "Dr. Smith"
   ↓
Voice AI calls: get_practitioner_calendars("Dr. Smith")
   ↓
MCP returns: Dr. Smith's calendar ID
   ↓
Voice AI calls: get_available_slots([calendar_id], "2025-11-18")
   ↓
MCP returns: Available times
   ↓
Voice AI presents options, caller chooses
   ↓
Voice AI uses standard HighLevel booking action with specific calendar_id

安装说明

1.将所需范围添加到您的私有集成令牌中

您的私有集成令牌需要以下权限：

1. 转到高级设置

- 设置→ 私人集成 - 找到您的集成（生成令牌的集成： pit-20de745d-406b-4d73-a9a2-445853979b6b) - 点击三个点→ Edit

1. 添加以下范围：

- ✅ calendars.readonly -需要列出和阅读日历 - ✅ calendars/events.readonly -需要阅读日历事件和免费插槽 - ✅ locations.readonly -需要获取位置详细信息（可选但推荐）

1. 点击保存

令牌将保持不变-您不需要重新生成它。作用域将立即更新。

2.测试连接

# Extract the ZIP (if you haven't already)
cd highlevel-calendar-mcp

# Install dependencies
npm install

# Test the connection with the official SDK
node test-sdk.js

如果测试成功，您应该看到：

✓ Found X calendars
  - Calendar 1 Name
  - Calendar 2 Name
  ...
✓ Found X available slots

如果您看到401错误，请仔细检查Private Integration中的作用域。

可用工具

MCP服务器将这些工具暴露给您的语音AI：

1. get_all_calendars

返回该位置的所有日历及其详细信息。

例子：

{
  "total": 10,
  "calendars": [
    {
      "id": "cal123",
      "name": "Dr. Smith - Adjustments",
      "services": "Chiropractic Adjustment",
      "teamMembers": ["Dr. Smith"]
    },
    ...
  ]
}

2. search_calendars_by_service

查找提供特定服务的日历。

参数：

• service_name （string）：要搜索的服务（不区分大小写，部分匹配）

例子：

search_calendars_by_service({ service_name: "adjustment" })
// Returns all calendars with "adjustment" in name, description, or event title

3. get_practitioner_calendars

获取特定从业者的日历。

参数：

• practitioner_name （string）：要搜索的从业者姓名

例子：

get_practitioner_calendars({ practitioner_name: "Dr. Smith" })
// Returns calendars associated with Dr. Smith

4. get_available_slots

获取特定日历的可用预约时段。

参数：

• calendar_ids （array）：要检查的日历ID数组
• start_date （字符串）：开始日期（YYYY-MM-DD）
• end_date （字符串，可选）：结束日期（默认为start_date）
• timezone （字符串，可选）：时区（默认值：“美国/纽约”）

例子：

get_available_slots({
  calendar_ids: ["cal123", "cal456"],
  start_date: "2025-11-18",
  timezone: "America/New_York"
})

5. find_next_available_slot

在多个日历中查找下一个可用插槽。

参数：

• calendar_ids （array）：要检查的日历ID数组
• start_date （string）：从此日期开始搜索
• days_to_search （数字，可选）：提前搜索的天数（默认值：7）
• timezone （字符串，可选）：时区（默认值：“美国/纽约”）

例子：

find_next_available_slot({
  calendar_ids: ["cal123", "cal456"],
  start_date: "2025-11-18",
  days_to_search: 14
})

在高级语音AI中配置

MCP服务器运行后：

1. 更新语音AI系统提示 包括：

You have access to calendar tools to check availability across multiple practitioners:

When a caller wants to schedule:
1. Ask what service they need (adjustment, massage, etc.)
2. Use search_calendars_by_service to find practitioners
3. Present options to the caller
4. Once they choose, use get_practitioner_calendars
5. Use get_available_slots to show times
6. After they pick a time, use the standard booking action with that calendar_id

Example:
Caller: "I need an adjustment"
You: *search_calendars_by_service("adjustment")*
You: "We have 10 practitioners: Dr. Smith, Dr. Jones... Who would you prefer?"
Caller: "Dr. Smith"
You: *get_practitioner_calendars("Dr. Smith")*
You: *get_available_slots with Dr. Smith's calendar*
You: "Dr. Smith is available Monday at 2pm, Tuesday at 10am..."

1. 配置MCP连接 高级：

- 转到您的语音AI设置 - 添加MCP服务器端点（您需要将其托管在可访问的地方） - 启动时，服务器将在stdio上运行 node index.js

托管选项

由于这是一个使用stdio的MCP服务器，您有几个选择：

选项1：直接集成（如果HighLevel支持）

如果HighLevel的MCP实现支持基于stdio的服务器，则可以直接运行它。

选项2：转换为HTTP API

您可以将其封装在Express服务器中，以公开HighLevel可以调用的HTTP端点。

选项3：部署到云端

部署到Railway、Render或VPS，并作为HTTP API公开。

您需要这些托管选项中的任何一个的帮助吗？

文件

• index.js -主MCP服务器代码
• test.js -API连接测试脚本
• .env -环境变量（API密钥和位置ID）
• package.json -Node.js依赖关系

环境变量

HIGHLEVEL_API_KEY=pit-20de745d-406b-4d73-a9a2-445853979b6b
HIGHLEVEL_LOCATION_ID=E2AMh5DDIIpOTRSYZnj4

故障排除

错误：“令牌未被授权用于此范围”

→ 在设置中添加所需的范围→ 私有集成（见上面的设置部分）

错误：“已超过重定向的最大数量”

→ 检查您是否正在使用正确的API端点： https://services.leadconnectorhq.com

未返回日历

→ 验证您的位置ID是否正确 → 检查该位置是否存在日历

后续步骤

1. 将所需范围添加到您的私有集成令牌中
2. 跑 node test.js 验证连接
3. 部署MCP服务器
4. 配置高级语音AI
5. 用电话测试！

问题？

如果您需要帮助，请告诉我：

• 添加更多工具/功能
• 托管服务器
• 高级配置
• 测试集成