内容
# GoHighLevel MCP 服务器
`ghl-mcp` 是适用于 GoHighLevel API v2 的模型上下文协议服务器。它通过 stdio 将联系人、机会、对话、日历、工作流程、用户、发票、付款、社交、表单、漏斗、任务、产品、电子邮件、活动和文档公开为 MCP 工具，以便 Claude Code、Cursor、Codex、OpenClaw、VS Code 等 MCP 客户端可以直接使用 GoHighLevel CRM 数据。
## 功能
- 50 个 MCP 工具，涵盖高价值的 GoHighLevel CRM、计费、营销和运营工作流程
- 基于 `@modelcontextprotocol/sdk` v1.x 构建
- 严格的 TypeScript 配置
- 使用 Zod 验证的工具输入，并为每个字段提供描述
- 从环境变量中自动注入 `locationId`
- 基本请求节奏控制，以保持在 GoHighLevel 速率限制之下
- 人类可读的工具错误负载，而不是原始堆栈跟踪
## 要求
- Node.js 18+
- GoHighLevel API令牌
- GoHighLevel 位置 ID
## 安装
### 本地开发
```bash
npm install
npm run build
node dist/index.js
```
### 使用 `npx` 运行
```bash
npx -y ghl-mcp
```
## 配置
在 MCP 客户端配置中设置以下环境变量：
- `GHL_API_TOKEN`：私有集成令牌或 OAuth 访问令牌
- `GHL_LOCATION_ID`：GoHighLevel 位置或子账户 ID
服务器在每个请求上发送以下标头：
```http
Authorization: Bearer {GHL_API_TOKEN}
Content-Type: application/json
Version: 2021-07-28
```
## MCP 客户端设置
### Claude Code
> **注意：** `claude mcp add` 注册一个本地服务器名称 - 它不从注册表中下载。`--` 之后的部分是实际运行服务器的命令。
```bash
# 发布后（推荐）：
claude mcp add gohighlevel --scope user \
--env GHL_API_TOKEN="your-token" \
--env GHL_LOCATION_ID="your-location-id" \
-- npx -y ghl-mcp
# 本地开发（发布前）：
claude mcp add gohighlevel --scope user \
--env GHL_API_TOKEN="your-token" \
--env GHL_LOCATION_ID="your-location-id" \
-- node /absolute/path/to/ghl-mcp/dist/index.js
```
### Cursor / VS Code / Codex 样式配置
```json
{
"mcpServers": {
"gohighlevel": {
"command": "npx",
"args": ["-y", "ghl-mcp"],
"env": {
"GHL_API_TOKEN": "your-token-here",
"GHL_LOCATION_ID": "your-location-id"
}
}
}
}
```
### MCP 检查器
```bash
npx @modelcontextprotocol/inspector node dist/index.js
```
## 工具列表
### 联系人
- `search_contacts`：按文本、标签、分页或高级筛选搜索联系人
- `get_contact`：按 ID 检索联系人
- `create_contact`：创建联系人
- `update_contact`：更新联系人字段
- `delete_contact`：删除联系人
- `add_contact_tags`：向联系人添加标签
- `remove_contact_tags`：从联系人中删除标签
- `get_contact_notes`：列出联系人的备注
- `create_contact_note`：在联系人上创建备注
### 机会
- `search_opportunities`：按查询、管道、阶段、状态、联系人或所有者搜索交易
- `get_opportunity`：按 ID 检索机会
- `create_opportunity`：创建机会
- `update_opportunity`：更新机会字段
- `delete_opportunity`：删除机会
- `update_opportunity_status`：将状态更改为 `open`、`won`、`lost` 或 `abandoned`
- `list_pipelines`：列出管道并获取其阶段
### 对话
- `search_conversations`：搜索对话
- `get_conversation`：按 ID 检索对话
- `get_conversation_messages`：列出对话中的消息
- `send_message`：发送 SMS、电子邮件、WhatsApp 或类似消息
- `create_conversation`：开始新的对话
### 日历
- `list_calendars`：列出日历
- `list_events`：列出事件或约会
- `create_event`：创建事件
- `get_available_slots`：检索可用预订时段
### 工作流程
- `list_workflows`：列出工作流程
- `trigger_workflow`：为联系人触发工作流程
### 用户
- `list_users`：列出配置位置的用户
- `get_user`：按 ID 检索用户
### 发票和付款
- `list_invoices`：列出发票
- `create_invoice`：创建发票
- `list_transactions`：列出付款交易
- `list_orders`：列出付款订单
- `list_subscriptions`：列出订阅
### 社交
- `list_social_posts`：列出社交帖子
- `create_social_post`：创建或安排社交帖子
- `list_social_accounts`：列出连接的社交账户
- `get_social_stats`：检索社交统计数据
### 表单和漏斗
- `list_forms`：列出表单
- `list_funnels`：列出漏斗
- `list_funnel_pages`：列出漏斗页面
### 任务
- `list_tasks`：列出联系人的任务
- `create_task`：为联系人创建任务
### 产品
- `list_products`：列出产品
- `list_product_prices`：列出产品的价格
### 电子邮件
- `list_email_templates`：列出电子邮件模板
- `list_email_schedules`：列出已安排的电子邮件
### 活动
- `list_campaigns`：列出活动
### 文档
- `list_contracts`：列出合同或文档
- `send_contract_link`：发送合同链接以供签署
## 开发
```bash
npm run dev
```
构建输出到 `dist/`。
## 架构
```text
src/
├── index.ts
├── client.ts
├── types.ts
└── tools/
├── calendars.ts
├── campaigns.ts
├── contacts.ts
├── conversations.ts
├── documents.ts
├── emails.ts
├── forms.ts
├── invoices.ts
├── opportunities.ts
├── products.ts
├── social.ts
├── tasks.ts
├── users.ts
└── workflows.ts
```
## 实现说明
- 大多数端点需要 `locationId`。此服务器自动将其注入请求查询字符串和 JSON 正文，除非已提供值。
- 客户端在请求之间应用最小延迟，以减少达到 GoHighLevel 速率限制的几率。
- 工具响应作为 JSON 文本块返回，带有简短摘要和原始 API 有效载荷。
- 管道列表获取每个返回管道的阶段详细信息，以便代理人在一次调用中获取可用的阶段元数据。
## 示例工作流程
### 查找联系人并添加备注
1. 调用 `search_contacts`，查询条件为 `"jane@company.com"`
2. 调用 `get_contact`，使用选定的 `contactId`
3. 调用 `create_contact_note`，使用 `contactId` 和备注文本
### 创建和推进机会
1. 调用 `list_pipelines` 以查找目标管道和阶段 ID
2. 调用 `create_opportunity`，使用 `contactId`、`pipelineId`、`pipelineStageId` 和 `name`
3. 随着交易进展，调用 `update_opportunity` 或 `update_opportunity_status`
### 预订约会
1. 调用 `get_available_slots`，使用 `calendarId` 和日期范围
2. 调用 `create_event`，使用选定的时间段和可选的 `contactId`
## 发布
```bash
npm publish --access public
```
已发布的包从 `dist/index.js` 安装 `ghl-mcp` 二进制文件。
