Gohighlevel MCP

🚀 GoHighLevel MCP Server

本項目通過MCP（模型上下文協議）將GoHighLevel社區與AI自動化相連接，為用戶提供了一個基礎層解決方案，可訪問所有子賬戶級別的GoHighLevel API端點，助力社區共同快速發展。

🎯 項目介紹

• 基礎層：通過MCP提供對所有子賬戶級別的GoHighLevel API端點的訪問權限。
• 社區起點：旨在推動社區更快地共同前進。
• 開放架構：API客戶端和類型可根據需要進一步模塊化和細分。
• 學習資源：學習如何將GoHighLevel與AI系統集成。

⚠️ 關鍵AI安全注意事項

• 內存/召回系統：如果未實施適當的內存或召回機制，AI可能會執行意外操作。
• 速率限制：監控API使用情況，避免達到GoHighLevel的速率限制。
• 權限控制：此項目提供對子賬戶API的完全訪問權限，請謹慎操作。
• 數據安全：所有操作均使用您的API憑證執行，請確保採取適當的安全措施。

🎯 預期用途

• 個人/商業用途：將您自己的GoHighLevel賬戶與AI集成。
• 開發基礎：在此基礎上構建自定義解決方案。
• 學習與實驗：瞭解GoHighLevel API模式。
• 社區貢獻：幫助改進和擴展這個基礎項目。

🚫 不適用場景

• 直接轉售：這是免費提供的社區軟件。
• 未經測試的生產環境：始終在開發環境中進行徹底測試。
• 無監控的AI使用：實施適當的保障措施和監控。

🚀 快速開始

本項目旨在通過MCP協議將GoHighLevel社區與AI自動化連接起來。在開始之前，請確保您已完成GoHighLevel API的設置，並獲取所需的API密鑰和位置ID。

✨ 主要特性

• 全面的工具集：提供269個操作工具，涵蓋19個類別，包括聯繫人管理、消息傳遞、博客管理等。
• 實時集成：與GoHighLevel實現實時集成，覆蓋完整的API。
• 多平臺部署：支持在Vercel、Railway、Render、Docker等多個平臺上進行生產就緒的部署。
• 企業級架構：具備全面的錯誤處理機制，確保系統的穩定性和可靠性。
• 完整的TypeScript支持：提供完整的類型定義，便於開發和維護。
• 廣泛的測試覆蓋：確保系統的可靠性和穩定性。
• Claude Desktop集成：與Claude Desktop集成，符合MCP協議。
• 社區驅動開發：擁有全面的文檔，方便社區成員參與和貢獻。

📦 安裝指南

本地開發

前提條件

• Node.js 18+（建議使用最新的LTS版本）
• 具有API訪問權限的GoHighLevel賬戶
• 有效的API密鑰和位置ID
• Claude Desktop（用於MCP集成）

安裝與設置

# 克隆倉庫
git clone https://github.com/mastanley13/GoHighLevel-MCP.git
cd GoHighLevel-MCP

# 安裝依賴
npm install

# 創建環境文件
cp .env.example .env
# 在.env文件中配置您的GHL憑證

# 構建項目
npm run build

# 啟動服務器
npm start

# 開發環境下使用熱重載
npm run dev

環境配置

# 必需的環境變量
GHL_API_KEY=your_private_integrations_api_key_here  # 來自私有集成，而非常規API密鑰
GHL_BASE_URL=https://services.leadconnectorhq.com
GHL_LOCATION_ID=your_location_id_here              # 來自設置 → 公司 → 位置
NODE_ENV=production

# 可選配置
PORT=8000
CORS_ORIGINS=*
LOG_LEVEL=info

可用腳本

npm run build          # TypeScript編譯
npm run dev            # 開發服務器，支持熱重載
npm start              # 生產環境HTTP服務器
npm run start:stdio    # 用於Claude Desktop的CLI MCP服務器
npm run start:http     # 用於Web應用的HTTP MCP服務器
npm test               # 運行測試套件
npm run test:watch     # 監視模式測試
npm run test:coverage  # 覆蓋率報告
npm run lint           # TypeScript代碼檢查

測試與驗證

# 測試API連接性
curl http://localhost:8000/health

# 列出可用工具
curl http://localhost:8000/tools

# 測試MCP SSE端點
curl -H "Accept: text/event-stream" http://localhost:8000/sse

部署指南

Vercel部署（推薦）

選項1：一鍵部署

選項2：手動部署

# 安裝Vercel CLI
npm i -g vercel

# 部署
vercel --prod

# 在Vercel控制檯中配置環境變量
# 添加：GHL_API_KEY、GHL_BASE_URL、GHL_LOCATION_ID、NODE_ENV

Vercel配置（vercel.json）：

{
  "version": 2,
  "builds": [
    {
      "src": "dist/http-server.js",
      "use": "@vercel/node"
    }
  ],
  "routes": [
    {
      "src": "/(.*)",
      "dest": "/dist/http-server.js"
    }
  ]
}

Railway部署

# 安裝Railway CLI
npm install -g @railway/cli

# 登錄並部署
railway login
railway init
railway up

# 通過Railway控制檯添加環境變量

Render部署

1. 連接您的GitHub倉庫。
2. 配置構建命令：npm run build。
3. 配置啟動命令：npm start。
4. 在Render控制檯中添加環境變量。

Docker部署

# 構建鏡像
docker build -t ghl-mcp-server .

# 運行容器
docker run -p 8000:8000 \
  -e GHL_API_KEY=your_key \
  -e GHL_BASE_URL=https://services.leadconnectorhq.com \
  -e GHL_LOCATION_ID=your_location_id \
  ghl-mcp-server

💻 使用示例

📞 客戶溝通工作流

"搜索標記為'VIP'且30天內未聯繫過的聯繫人，然後向他們發送一條關於我們新高級服務的個性化短信"

💰 銷售管道管理

"為聯繫人John Smith創建一個價值5000美元的高級套餐機會，將其添加到'企業銷售'管道中，並安排下週二的跟進預約"

📊 商業智能

"獲取上一季度的所有發票，分析付款模式，並創建一份關於我們最高付費客戶及其終身價值的報告"

🛒 電子商務運營

"列出所有庫存不足的產品，創建一個補貨通知活動，並將其發送給標記為'庫存管理員'的聯繫人"

📱 社交媒體自動化

"創建一條宣佈我們黑色星期五促銷活動的社交媒體帖子，安排在所有連接的平臺上發佈，並跟蹤參與度指標"

🎯 營銷自動化

"查找所有打開了我們上一次電子郵件活動但未購買的聯繫人，將他們添加到'潛在客戶'工作流中，並安排後續跟進序列"

📚 詳細文檔

項目架構

ghl-mcp-server/
├── 📁 src/                    # 源代碼
│   ├── 📁 clients/            # API客戶端實現
│   │   └── ghl-api-client.ts  # 核心GHL API客戶端
│   ├── 📁 tools/              # MCP工具實現
│   │   ├── contact-tools.ts   # 聯繫人管理（31個工具）
│   │   ├── conversation-tools.ts # 消息傳遞（20個工具）
│   │   ├── blog-tools.ts      # 博客管理（7個工具）
│   │   ├── opportunity-tools.ts # 銷售管道（10個工具）
│   │   ├── calendar-tools.ts  # 預約管理（14個工具）
│   │   ├── email-tools.ts     # 電子郵件營銷（5個工具）
│   │   ├── location-tools.ts  # 位置管理（24個工具）
│   │   ├── email-isv-tools.ts # 電子郵件驗證（1個工具）
│   │   ├── social-media-tools.ts # 社交媒體（17個工具）
│   │   ├── media-tools.ts     # 媒體庫（3個工具）
│   │   ├── object-tools.ts    # 自定義對象（9個工具）
│   │   ├── association-tools.ts # 關聯管理（10個工具）
│   │   ├── custom-field-v2-tools.ts # 自定義字段（8個工具）
│   │   ├── workflow-tools.ts  # 工作流管理（1個工具）
│   │   ├── survey-tools.ts    # 調查管理（2個工具）
│   │   ├── store-tools.ts     # 商店管理（18個工具）
│   │   ├── products-tools.ts  # 產品管理（10個工具）
│   │   ├── payments-tools.ts  # 支付管理（20個工具）
│   │   └── invoices-tools.ts  # 發票與賬單管理（39個工具）
│   ├── 📁 types/              # TypeScript類型定義
│   │   └── ghl-types.ts       # 全面的類型定義
│   ├── 📁 utils/              # 實用函數
│   ├── server.ts              # CLI MCP服務器（Claude Desktop）
│   └── http-server.ts         # HTTP MCP服務器（Web應用）
├── 📁 tests/                  # 全面的測試套件
│   ├── 📁 clients/            # API客戶端測試
│   ├── 📁 tools/              # 工具實現測試
│   └── 📁 mocks/              # 測試模擬和夾具
├── 📁 api/                    # Vercel API路由
├── 📁 docker/                 # Docker配置
├── 📁 dist/                   # 編譯後的JavaScript（自動生成）
├── 📄 文檔文件
│   ├── DEPLOYMENT.md          # 部署指南
│   ├── CLAUDE-DESKTOP-DEPLOYMENT-PLAN.md
│   ├── VERCEL-DEPLOYMENT.md
│   ├── CLOUD-DEPLOYMENT.md
│   └── PROJECT-COMPLETION.md
├── 📄 配置文件
│   ├── package.json           # 依賴項和腳本
│   ├── tsconfig.json          # TypeScript配置
│   ├── jest.config.js         # 測試配置
│   ├── vercel.json            # Vercel部署配置
│   ├── railway.json           # Railway部署配置
│   ├── Dockerfile             # Docker容器化配置
│   ├── Procfile               # 進程配置
│   └── cursor-mcp-config.json # MCP配置
└── 📄 README.md               # 本綜合指南

安全與最佳實踐

環境安全

• ✅ 切勿將API密鑰提交到版本控制中。
• ✅ 使用環境變量存儲所有敏感數據。
• ✅ 實施適當的CORS策略。
• ✅ 定期輪換API密鑰。
• ✅ 監控API使用情況和速率限制。

生產環境考慮

• ✅ 實施適當的錯誤處理和日誌記錄。
• ✅ 設置監控和警報。
• ✅ 所有部署均使用HTTPS。
• ✅ 實施請求速率限制。
• ✅ 定期進行安全更新。

API速率限制

• GoHighLevel API有速率限制。
• 實施指數退避策略。
• 緩存頻繁請求的數據。
• 儘可能使用批量操作。

故障排除指南

常見問題與解決方案

構建失敗：

# 清除緩存並重新安裝
rm -rf node_modules package-lock.json dist/
npm install
npm run build

API連接問題：

# 測試API連接性（使用您的私有集成API密鑰）
curl -H "Authorization: Bearer YOUR_PRIVATE_INTEGRATIONS_API_KEY" \
     https://services.leadconnectorhq.com/locations/YOUR_LOCATION_ID

常見API問題：

• ✅ 使用私有集成API密鑰（而非常規API密鑰）。
• ✅ 在私有集成中啟用所需的作用域。
• ✅ 位置ID與您的GHL賬戶匹配。
• ✅ 正確設置環境變量。

Claude Desktop集成問題：

1. 驗證MCP配置語法。
2. 檢查文件路徑是否為絕對路徑。
3. 確保環境變量已設置。
4. 更改後重新啟動Claude Desktop。

內存問題：

# 增加Node.js內存限制
node --max-old-space-size=8192 dist/server.js

CORS錯誤：

• 配置CORS_ORIGINS環境變量。
• 確保HTTP頭正確。
• 檢查域名白名單。

性能優化

• 為讀取操作啟用響應緩存。
• 對大數據集使用分頁。
• 實施連接池。
• 監控內存使用情況並相應地進行優化。

🔧 技術細節

系統要求

• 運行時：Node.js 18+（建議使用最新的LTS版本）
• 內存：最小512MB RAM，推薦1GB以上
• 存儲：應用程序需要100MB，日誌需要額外空間
• 網絡：穩定的互聯網連接，用於API調用

技術棧

• 後端：Node.js + TypeScript
• HTTP框架：Express.js 5.x
• MCP SDK：@modelcontextprotocol/sdk ^1.12.1
• HTTP客戶端：Axios ^1.9.0
• 測試：Jest，支持TypeScript
• 構建系統：TypeScript編譯器

API集成

• GoHighLevel API：v2021-07-28（聯繫人），v2021-04-15（對話）
• 身份驗證：Bearer令牌
• 速率限制：遵守GHL API限制
• 錯誤處理：全面的錯誤恢復機制

性能指標

• 冷啟動：< 2秒
• API響應：平均< 500ms
• 內存使用：基礎約50 - 100MB
• 工具執行：平均< 1秒

📄 許可證

本項目採用ISC許可證，詳情請參閱LICENSE文件。

🆘 社區與支持

文檔

• 📖 完整API文檔
• 🎥 視頻教程
• 📋 工具參考指南
• 🔧 部署指南

獲取幫助

• 問題反饋：GitHub Issues
• 討論交流：GitHub Discussions
• API參考：GoHighLevel API文檔
• MCP協議：模型上下文協議

社區資源

• 💬 加入我們的Discord社區
• 📺 訂閱我們的YouTube頻道
• 📰 關注我們的開發博客
• 🐦 關注我們的Twitter獲取更新

🎉 成功指標

• ✅ 269個操作工具，涵蓋19個類別
• ✅ 實時GoHighLevel集成，全面覆蓋API
• ✅ 多平臺生產就緒部署
• ✅ 企業級架構，具備全面的錯誤處理機制
• ✅ 完整的TypeScript支持，提供完整的類型定義
• ✅ 廣泛的測試覆蓋，確保可靠性
• ✅ 多平臺部署（Vercel、Railway、Render、Docker）
• ✅ Claude Desktop集成，符合MCP協議
• ✅ 社區驅動開發，擁有全面的文檔

🚀 準備好徹底改變您的GoHighLevel自動化了嗎？

立即部署，釋放AI驅動的CRM管理的全部潛力！

💝 支持本項目

本項目凝聚了數百小時的開發工作，旨在幫助GoHighLevel社區。如果它為您節省了時間並對您的業務有所幫助，請考慮支持其持續發展：

🎁 支持方式

• ⭐ 給這個倉庫加星：幫助他人發現該項目。
• 🍕 請我吃披薩：通過Stripe捐贈
• 🐛 報告漏洞：幫助大家讓項目變得更好。
• 💡 提出功能建議：分享您的改進想法。
• 🤝 貢獻代碼：隨時歡迎提交拉取請求！

🏆 認可方式

• 貢獻者將在項目中列出。
• 重大貢獻可能會獲得特別認可。
• 本項目由社區驅動並得到社區支持。

每一份貢獻，無論大小，都有助於讓這個項目持續發展！ 🚀

由瞭解自動化力量的開發者為GoHighLevel社區精心打造 ❤️