Dlf Ghl MCP

DLF代理MCP服务器

遥控器 模型上下文协议 （MCP）服务器，让AI代理完全控制 GoHighLevel.部署为Cloudflare Worker，具有用户密钥身份验证、每个用户范围、多帐户支持和管理面板。

508工具 跨越18个领域模块，覆盖整个GHL API v2 surface+内部工作流生成器API。

居住地址： https://dlf-agency.skool-203.workers.dev

它的作用

将任何兼容MCP的AI客户端（Claude Code、Claude Desktop、Cursor、Windsurf、自定义代理）连接到您的GoHighLevel帐户。然后，AI可以通过自然语言管理您的整个GHL工作空间：

• *“显示本周的所有约会”*
• *“通过电子邮件创建一个名为John Smith的新联系人john@example.com"*
• *“在我的渠道中搜索超过5000美元的交易”*
• *“为短信自动回复创建会话AI代理”*
• *“列出过去30天的所有发票”*
• *“构建在表单提交时触发的工作流”*

快速入门（以用户身份连接）

1.获取API密钥

首选 https://dlf-agency.skool-203.workers.dev/signup 并注册。你的钥匙(uk_...)如图所示 一次 --立即复制。管理员必须批准您的帐户才能正常工作。

2.连接您的MCP客户端

克劳德代码：

claude mcp add --transport http \
  --header "X-User-Key: uk_YOUR_KEY_HERE" \
  dlf-agency https://dlf-agency.skool-203.workers.dev/mcp

克劳德桌面/光标/任何MCP客户端(.mcp.json):

{
  "mcpServers": {
    "dlf-agency": {
      "type": "http",
      "url": "https://dlf-agency.skool-203.workers.dev/mcp",
      "headers": {
        "X-User-Key": "uk_YOUR_KEY_HERE"
      }
    }
  }
}

3.开始使用它

连接后，让你的AI在GHL中做任何事情：

"List all contacts tagged 'hot-lead'"
"Send an SMS to contact ID xyz saying 'Hey, following up on our call'"
"Create a calendar event for tomorrow at 2pm"

建筑

MCP Client (Claude Code, Cursor, etc.)
  │
  │  HTTPS + X-User-Key header
  ▼
Cloudflare Worker (outer wrapper)
  │
  ├── Validates API key against D1 (SHA-256 hashed)
  ├── Stores auth context in KV (scopes + allowed accounts)
  ├── Passes user ID via URL query param
  │
  ▼
GHLMcpAgent (Durable Object)
  │
  ├── Reads auth from KV (scopes, allowed accounts)
  ├── Enforces per-tool scope checks (default-deny)
  ├── resolveClient() → picks correct GHL API key for the location
  │
  ▼
GoHighLevel REST API (services.leadconnectorhq.com)

为什么选择KV认证？

MCP SDK McpAgent.serve() 在内部创建一个WebSocket升级请求，删除所有自定义标头。仅 x-partykit-room （会话ID）和 Upgrade 生存。因此，我们将身份验证上下文存储在以用户ID为键的KV中，持久对象从那里读取它。

所有路线

认证

用户密钥认证（主要——适用于MCP客户端）

每一个请求 /mcp 必须包含API密钥：

Header: X-User-Key: uk_58894012-805b-4081-89c8-2ad0391e6c2b

密钥生成于 /signup 或由管理员。它们在存储之前经过SHA-256哈希处理——原始密钥只显示一次，永远无法恢复。

用户生命周期：

1. 用户注册地址： /signup ->状态= pending
2. 管理员在管理面板->状态中批准= active
3. 管理员可以随时禁用->状态= disabled

按用户访问控制：

• 范围：用户可以调用的工具名称的JSON数组（例如。， ["ghl_get_contact", "ghl_send_message"])，或 ["*"] 所有508个工具
• 允许的帐户：用户可以访问的GHL位置ID的JSON数组（例如。， ["W7BRJwzJCvFs9r0xZHrE"])，或 ["*"] 对于所有

GHL OAuth（用于添加位置）

要连接新的GHL位置（子帐户）：

1. 访问 GET /install --返回GHL OAuth选择位置URL
2. 在浏览器中打开该URL——选择要安装的GHL位置
3. GHL重定向到 /callback?code=xxx
4. 服务器交换访问+刷新令牌的代码
5. 令牌与位置ID一起存储在D1中
6. 代币到期时自动刷新（24小时生命周期）

这使用具有以下凭据的GHL Marketplace OAuth流：

• 客户端ID：通过设置 GHL_CLIENT_ID 秘密
• 客户端密钥：通过设置 GHL_CLIENT_SECRET 秘密
• 重定向URI: https://dlf-agency.skool-203.workers.dev/callback

私有集成令牌（PIT）

对于不使用OAuth的位置，您可以使用GHL私有集成令牌手动添加它们：

1. 在GHL中：设置>集成>私有集成>创建
2. 复制令牌
3. 使用 ghl_add_sub_account 工具或管理面板添加位置及其PIT

PIT不会过期，但也不能自动刷新。OAuth令牌是首选。

管理面板

网址： https://dlf-agency.skool-203.workers.dev/admin

特征：

• 查看、创建、编辑和删除用户
• 设置每个用户的范围（他们可以使用哪些工具）
• 设置每个用户帐户的访问权限（他们可以访问哪些GHL位置）
• 查看和管理子帐户
• 具有类别预设的范围选择器（完整/只读/无）

登录需要 ADMIN_PASSWORD 秘密。

工具域（508个工具）

Beta版：工作流生成器（16个工具）

工作流生成器工具使用 内部GHL API (backend.leadconnectorhq.com)使用Firebase身份验证。这些不是官方GHL REST API的一部分，可能会在不通知的情况下更改。

工具： ghl_workflow_builder_list, ghl_workflow_builder_create, ghl_workflow_builder_get, ghl_workflow_builder_get_steps, ghl_workflow_builder_get_triggers, ghl_workflow_builder_update, ghl_workflow_builder_save_steps, ghl_workflow_builder_publish, ghl_workflow_builder_draft, ghl_workflow_builder_delete, ghl_workflow_builder_create_trigger, ghl_workflow_builder_update_trigger, ghl_workflow_builder_delete_trigger, ghl_workflow_builder_create_folder, ghl_workflow_builder_clone, ghl_workflow_builder_error_count

状态： 贝塔。这些工具可能无法可靠地用于创建/更新操作。读取操作（list、get）是稳定的。

需要 GHL_FIREBASE_REFRESH_TOKEN 秘密有待设定。

禁用：管道写入操作

三个管道工具被禁用，因为GHL对所有令牌类型都返回401：

• ghl_create_pipeline --残疾人
• ghl_update_pipeline --残疾人
• ghl_delete_pipeline --残疾人

读取管道(ghl_list_pipelines, ghl_get_pipeline)工作得很好。写入操作需要单独的 opportunities.pipeline.write GHL目前在私有集成或OAuth令牌授予中未公开的范围。

代码保存在 src/tools/_disabled/pipeline-write.ts 当GHL修复此问题时，可以重新启用。

子账户管理

服务器支持多个GHL位置（子帐户）。每个都有自己的API密钥存储在D1中。

解析顺序 （当调用工具时）：

1. 如果 locationId 在工具args中传递->使用D1中的该位置的键
2. 如果不 locationId ->使用D1中的默认帐户
3. 如果D1中没有违约->回退到 GHL_API_KEY + GHL_LOCATION_ID 环境变量

令牌类型：

• OAuth令牌：有 refresh_token + expires_at到期前自动刷新。
• 私有集成令牌：静态，永不过期，无需刷新。

项目结构

dlf-ghl-mcp-server/
├── src/
│   ├── index.ts                    # Worker entry: auth wrapper + GHLMcpAgent DO
│   ├── types.ts                    # Env, User, SubAccount, ApiVersion types
│   ├── config.ts                   # API base URL, versions, MCP server metadata
│   │
│   ├── client/                     # GHL API client layer (makes HTTP calls)
│   │   ├── base.ts                 # BaseGHLClient -- fetch wrapper with auth headers
│   │   ├── index.ts                # GHLClient -- composes all 16 domain factories
│   │   ├── ai-agents.ts            # Voice AI, Conversation AI, Agent Studio
│   │   ├── automation.ts           # Workflows, forms, surveys
│   │   ├── businesses.ts           # Business CRUD
│   │   ├── calendars.ts            # Calendars, events, bookings, services
│   │   ├── contacts.ts             # Contacts, notes, tasks, tags
│   │   ├── content.ts              # Blogs, media, documents, menus, snapshots
│   │   ├── conversations.ts        # Messages, calls, transcriptions
│   │   ├── knowledge-base.ts       # KBs, FAQs, crawlers
│   │   ├── locations.ts            # Locations, users, custom fields
│   │   ├── marketing.ts            # Social, email, campaigns, funnels, links
│   │   ├── marketplace.ts          # Billing, app installations
│   │   ├── misc.ts                 # Companies, phone, products, objects, brands
│   │   ├── opportunities.ts        # Opportunities, pipelines
│   │   ├── payments.ts             # Invoices, orders, subscriptions, coupons
│   │   ├── saas.ts                 # SaaS rebilling, wallets
│   │   └── workflow-builder.ts     # Internal GHL API (Firebase auth) -- BETA
│   │
│   ├── tools/                      # MCP tool registrations (Zod schemas + handlers)
│   │   ├── index.ts                # registerAllTools() -- calls all 18 domain modules
│   │   ├── _helpers.ts             # ok(), err(), resolveClient() shared utilities
│   │   ├── _disabled/
│   │   │   └── pipeline-write.ts   # Pipeline CRUD (disabled -- GHL returns 401)
│   │   ├── accounts.ts             # 5 tools
│   │   ├── ai-agents.ts            # 26 tools
│   │   ├── automation.ts           # 11 tools
│   │   ├── businesses.ts           # 5 tools
│   │   ├── calendars.ts            # 56 tools
│   │   ├── contacts.ts             # 27 tools
│   │   ├── content.ts              # 41 tools
│   │   ├── conversations.ts        # 22 tools
│   │   ├── errors.ts               # 2 tools
│   │   ├── knowledge-base.ts       # 14 tools
│   │   ├── locations.ts            # 45 tools
│   │   ├── marketing.ts            # 70 tools
│   │   ├── marketplace.ts          # 9 tools
│   │   ├── misc.ts                 # 66 tools
│   │   ├── opportunities.ts        # 12 tools
│   │   ├── payments.ts             # 68 tools
│   │   ├── saas.ts                 # 13 tools
│   │   └── workflow-builder.ts     # 16 tools (BETA)
│   │
│   ├── db/
│   │   ├── accounts.ts             # D1: sub_accounts + oauth_tokens tables
│   │   ├── users.ts                # D1: users table, API key hashing
│   │   └── errors.ts               # D1: error capture table
│   │
│   ├── handlers/
│   │   ├── admin.ts                # Admin panel (HTML dashboard + REST API)
│   │   ├── oauth-callback.ts       # GHL OAuth code exchange + token storage
│   │   └── register.ts             # User self-registration form
│   │
│   └── utils/
│       ├── errors.ts               # GHLError class (statusCode + details)
│       ├── logger.ts               # Structured JSON logger with field redaction
│       ├── rate-limit.ts           # KV-based sliding window rate limiter
│       └── webhook.ts              # Optional error webhook sender
│
├── scripts/
│   ├── deploy.sh                   # Full deploy pipeline (both workers)
│   ├── check-duplicates.sh         # Detect duplicate tool names (crash prevention)
│   ├── count-tools.sh              # Tool count per domain (--detail for names)
│   ├── add-domain.sh               # Scaffold new domain module pair
│   └── add-tool.sh                 # Add tool to existing domain
│
├── migrations/
│   ├── 0001_create_users_table.sql
│   └── 0002_add_allowed_accounts.sql
│
├── wrangler.toml                   # Cloudflare Worker config (bindings, DO, D1, KV)
├── tsconfig.json
├── package.json
└── SERVER-MAP.md                   # Quick reference with all tool names + scope presets

两层模块模式

每个GHL API域都有一对并行文件：

src/client/.ts   ->  Factory function returning async methods (HTTP calls)
src/tools/.ts    ->  registerXxxTools(server, env) registering MCP tools

客户端层：每个文件导出一个 domainMethods(client) 工厂。 GHLClient 它的建造者拥有全部16家工厂。

工具层：每个文件导出一个 registerXxxTools(server, env) 功能。 registerAllTools() 调用所有18个注册功能 GHLMcpAgent.init().

部署

需求

• Cloudflare员工 账户
• 18+
• 具有API访问权限的GHL帐户
• GHL OAuth应用程序凭据（用于OAuth安装流程）

从头开始设置

git clone https://github.com/Bladefitness/dlf-ghl-mcp.git
cd dlf-ghl-mcp/dlf-ghl-mcp-server
npm install

# Create Cloudflare resources
npx wrangler d1 create ghl-accounts
npx wrangler kv namespace create OAUTH_KV

# Update wrangler.toml with the IDs from above

# Set required secrets
echo "your-admin-password" | npx wrangler secret put ADMIN_PASSWORD
echo "your-admin-pin" | npx wrangler secret put ADMIN_PIN
echo "your-ghl-client-id" | npx wrangler secret put GHL_CLIENT_ID
echo "your-ghl-client-secret" | npx wrangler secret put GHL_CLIENT_SECRET

# Optional: for workflow builder tools
echo "your-firebase-refresh-token" | npx wrangler secret put GHL_FIREBASE_REFRESH_TOKEN

# Deploy
npm run deploy

# Verify
curl https://your-worker.workers.dev/health

秘密参考

Cloudflare绑定

部署脚本

# Full pipeline: duplicate check -> tsc -> deploy both workers -> health verify
./scripts/deploy.sh

# Dry run (no actual deploy)
./scripts/deploy.sh --dry-run

# Deploy only one worker
./scripts/deploy.sh --one dlf-agency

安全

GHL API版本

每个客户端模块中的每个端点都会自动设置正确的版本。

添加新工具

将工具添加到现有域

# Scaffold both client method + tool registration
./scripts/add-tool.sh contacts ghl_archive_contact

# Or manually:
# 1. Add method to src/client/contacts.ts
# 2. Add server.tool() to src/tools/contacts.ts
# 3. Run ./scripts/check-duplicates.sh to verify no name collision

添加新域

# Scaffold the full module pair
./scripts/add-domain.sh new-domain

# Then wire it up:
# 1. Import factory in src/client/index.ts
# 2. Import register function in src/tools/index.ts

D1数据库架构

用户

id TEXT PRIMARY KEY,
name TEXT NOT NULL,
email TEXT NOT NULL UNIQUE,
api_key TEXT NOT NULL UNIQUE,           -- SHA-256 hash of uk_
status TEXT DEFAULT 'pending',          -- 'pending' | 'active' | 'disabled'
scopes TEXT DEFAULT '["*"]',            -- JSON array of tool names or ["*"]
allowed_accounts TEXT DEFAULT '["*"]',  -- JSON array of location IDs or ["*"]
created_at TEXT, updated_at TEXT, notes TEXT

sub_计数

id TEXT PRIMARY KEY,                    -- GHL Location ID
name TEXT NOT NULL,
api_key TEXT NOT NULL,                  -- Bearer token (PIT or OAuth)
account_type TEXT DEFAULT 'sub_account', -- 'sub_account' | 'oauth_location'
is_default INTEGER DEFAULT 0,
refresh_token TEXT,                     -- OAuth only
expires_at INTEGER,                     -- Unix timestamp, OAuth only
notes TEXT, created_at TEXT, updated_at TEXT

成本

对于个人/小团队使用，这通常保持在免费等级限制范围内。

许可证

Apache 2.0