Ghl MCP Server

🚀 GoHighLevel MCP 服務器

這是一個模型上下文協議（MCP）服務器，可與 GoHighLevel API v2 進行全面集成。該服務器使 AI 助手能夠與 GoHighLevel 的客戶關係管理（CRM）、營銷自動化和業務管理工具進行交互。

✨ 主要特性

• 🚀 完整的 API 覆蓋：可訪問聯繫人、對話、日曆、銷售機會、支付、工作流等功能。
• 🔐 靈活的身份驗證：支持 OAuth 2.0 和私有集成令牌兩種方式。
• ⚡ 內置速率限制：自動進行速率限制管理（每 10 秒 100 個請求，每天 200,000 個請求）。
• 🛡️ 錯誤處理：具備全面的錯誤處理機制，提供詳細的錯誤信息。
• 📦 支持 Vercel 部署：專為在 Vercel 上部署而設計，支持 MCP。
• 🎯 類型安全：對所有工具進行全面的輸入驗證和模式定義。

📦 安裝指南

可以使用以下命令進行安裝：

npm install ghl-mcp-server

或者進行全局安裝：

npm install -g ghl-mcp-server

🚀 快速開始

1. 設置環境變量

將 .env.example 文件複製為 .env，並填寫你的憑證信息：

cp .env.example .env

編輯 .env 文件，填入你的 GoHighLevel 憑證：

# 私有集成令牌（最簡單的方法）
GHL_PRIVATE_TOKEN=your_private_integration_token_here

# 或者使用 OAuth（用於多賬戶訪問）
GHL_CLIENT_ID=your_oauth_client_id
GHL_CLIENT_SECRET=your_oauth_client_secret

2. 配置你的 MCP 客戶端

將以下內容添加到你的 Claude Desktop 或其他 MCP 客戶端配置中：

{
  "mcpServers": {
    "ghl": {
      "command": "npx",
      "args": ["ghl-mcp-server"],
      "env": {
        "GHL_PRIVATE_TOKEN": "your_token_here"
      }
    }
  }
}

3. 開始使用 GoHighLevel 工具

該服務器提供以下工具：

聯繫人管理

• ghl_create_contact - 創建新聯繫人
• ghl_search_contacts - 搜索聯繫人
• ghl_get_contact - 獲取聯繫人詳情
• ghl_update_contact - 更新聯繫人信息
• ghl_delete_contact - 刪除聯繫人
• ghl_add_contact_tags - 為聯繫人添加標籤
• ghl_remove_contact_tags - 移除聯繫人的標籤

對話與消息

• ghl_send_message - 發送短信、電子郵件或 WhatsApp 消息
• ghl_get_conversations - 獲取對話列表
• ghl_get_messages - 獲取對話中的消息

日曆與預約

• ghl_create_calendar - 創建新日曆
• ghl_create_appointment - 預訂預約
• ghl_get_calendar_slots - 獲取可用時間段
• ghl_update_appointment - 更新預約詳情
• ghl_cancel_appointment - 取消預約

銷售與機會

• ghl_create_opportunity - 創建銷售機會
• ghl_search_opportunities - 搜索銷售機會
• ghl_update_opportunity - 更新銷售機會詳情
• ghl_delete_opportunity - 刪除銷售機會
• ghl_get_pipelines - 獲取銷售管道列表

支付

• ghl_create_order - 創建支付訂單
• ghl_get_transactions - 獲取交易歷史
• ghl_get_orders - 獲取訂單列表

自動化

• ghl_add_contact_to_workflow - 將聯繫人添加到工作流
• ghl_remove_contact_from_workflow - 從工作流中移除聯繫人
• ghl_get_workflows - 獲取工作流列表

💻 使用示例

基礎用法

創建聯繫人

{
  "tool": "ghl_create_contact",
  "arguments": {
    "locationId": "your_location_id",
    "contactData": {
      "firstName": "John",
      "lastName": "Doe",
      "email": "john.doe@example.com",
      "phone": "+1234567890",
      "tags": ["new-lead", "website"]
    }
  }
}

發送消息

{
  "tool": "ghl_send_message",
  "arguments": {
    "type": "SMS",
    "contactId": "contact_id",
    "locationId": "location_id",
    "message": "Hello! Thanks for your interest."
  }
}

創建預約

{
  "tool": "ghl_create_appointment",
  "arguments": {
    "appointmentData": {
      "calendarId": "calendar_id",
      "locationId": "location_id",
      "contactId": "contact_id",
      "startTime": "2025-07-23T15:00:00Z",
      "endTime": "2025-07-23T16:00:00Z",
      "title": "Consultation Call"
    }
  }
}

🔐 身份驗證方法

方法 1：私有集成令牌（適用於單賬戶，推薦使用）

1. 進入 GoHighLevel 的“設置”>“集成”>“私有集成”。
2. 創建一個新的私有集成。
3. 複製令牌並添加到你的 .env 文件中。

方法 2：OAuth 2.0（適用於市場應用）

1. 在 GoHighLevel 市場中註冊你的應用。
2. 使用所需的範圍設置 OAuth。
3. 通過 OAuth 流程獲取訪問令牌。

🔧 技術細節

本地運行

# 安裝依賴
npm install

# 在開發模式下運行
npm run dev

項目結構

ghl-mcp-server/
├── index.js              # 主服務器入口點
├── src/
│   ├── api-client.js     # GoHighLevel API 客戶端
│   ├── config.js         # 配置常量
│   ├── rate-limiter.js   # 速率限制邏輯
│   ├── error-handler.js  # 錯誤處理工具
│   └── tools/            # 工具定義
│       ├── contact-tools.js
│       ├── conversation-tools.js
│       ├── calendar-tools.js
│       ├── opportunity-tools.js
│       ├── payment-tools.js
│       └── workflow-tools.js
└── package.json

🚀 部署到 Vercel

1. 分叉此倉庫。
2. 連接到 Vercel。
3. 在 Vercel 控制檯中設置環境變量。
4. 進行部署。

該服務器設計為可直接與 Vercel 的 MCP 集成配合使用。

🛡️ 錯誤處理

服務器針對常見場景提供詳細的錯誤信息：

• 401 未授權：令牌無效或已過期。
• 403 禁止訪問：權限/範圍不足。
• 404 未找到：資源未找到。
• 429 速率限制：請求過多。
• 422 不可處理的實體：驗證錯誤。

⚡ 速率限制

GoHighLevel 實施以下速率限制：

• 突發：每 10 秒 100 個請求。
• 每日：每天 200,000 個請求。

服務器會自動跟蹤並執行這些限制。

🤝 貢獻

歡迎貢獻代碼！請隨時提交拉取請求。

📄 許可證

本項目採用 MIT 許可證。

📚 支持

• GoHighLevel API 文檔
• MCP 文檔
• 問題反饋