使用说明

高级MCP服务器

多账户高级CRM MCP服务器，集成OAuth，通过统一界面管理30多个子账户。

概述

此MCP（模型上下文协议）服务器使TypingMind、ClickUp Brain和其他MCP客户端等AI代理能够通过单个统一界面与多个高级CRM子账户进行交互。此服务器利用存储在Supabase中的现有OAuth令牌，而不是管理30多个私有集成令牌（PIT）。

主要特点

🔐 OAuth集成 -使用Supabase中的现有访问令牌
🏢 多账户支持 -通过一个连接管理30多个高级子账户
⚡ 18只读API工具 -联系人、对话、机会、日历、位置、付款和实用程序（默认情况下禁用写入操作）
🔌 双重运输 -流式HTTP(POST /mcp)面向现代客户+传统SSE(GET /sse)打字思维
🚀 Cloudflare员工 -跨工作隔离的无服务器、无状态会话处理
💾 智能缓存 -5分钟令牌缓存，实现最佳性能
🎯 客户友好 -交替使用客户端名称或位置ID
📋 日历发现 - get-calendars / calendars_get-calendars 工具加上自动发现 calendars_get-calendar-events

为什么存在

HighLevel的官方MCP服务器要求每个子账户有一个私有集成令牌（PIT）。对于管理30多个客户的机构来说，这意味着：

❌ 通过UI手动创建30+个PIT
❌ 管理30多个单独的MCP连接
❌ 无程序化令牌管理

我们的解决方案：

✅ 重用Supabase数据库中的现有OAuth令牌
✅ 所有客户端都有一个MCP连接
✅ 带缓存的自动令牌管理

建筑

┌──────────────────────────────┐
│  AI Clients                  │
│  (TypingMind, ClickUp, etc.) │
└──────────────┬───────────────┘
               │ MCP Protocol
               │  • Streamable HTTP → POST /mcp
               │  • Legacy SSE      → GET /sse
               │
┌──────────────▼────────────────────────┐
│ Cloudflare Worker                     │
│ ┌───────────────────────────────────┐ │
│ │ Token Manager (5min cache)        │ │
│ └───────────────┬───────────────────┘ │
│                 │                       │
│ ┌───────────────▼───────────────────┐ │
│ │ 18 Read-Only API Tools            │ │
│ └───────────────┬───────────────────┘ │
└─────────────────┼─────────────────────┘
                  │
          ┌───────▼────────┐
          │   Supabase     │
          │ ┌────────────┐ │
          │ │ locations  │ │
          │ │ - access_  │ │
          │ │   token    │ │
          │ └────────────┘ │
          └────────────────┘
                  │
          ┌───────▼──────────────┐
          │ HighLevel REST API   │
          │ 30+ Sub-Accounts     │
          └──────────────────────┘

端点

端点	方法	目的
`/`	GET	运行状况检查（不需要API密钥）
`/mcp`	POST	流式HTTP MCP传输（ClickUp，现代客户端）
`/mcp`	DELETE	终止MCP会话
`/sse`	GET	传统SSE连接（TypingMind）
`/sse`	POST	直接MCP消息（无会话）
`/sse/message`	POST	带SSE会话的MCP消息

健康检查响应 包括 version, toolCount, calendarTools，并且可用 endpoints.

MCP协议版本： 2025-03-26 （以前 2024-11-05)

身份验证： 除以下端点外的所有端点 / 需要通过 X-API-Key 头球

会话处理： 流式HTTP使用无状态 Mcp-Session-Id 标头（无内存会话存储），这是Cloudflare Workers所必需的，因为请求可能会到达不同的隔离区。

可用工具（18个只读）

注：为了安全起见，默认情况下禁用写入/更新/删除操作。要启用它们，请取消注释中的相关工具 src/index.ts.

联系人（3个活动，5个禁用）

contacts_get-contact -获取联系方式
contacts_get-contacts -列出所有联系人
contacts_get-all-tasks -获取联系人任务
~~contacts_create-contact~~-创建新联系人 （残疾）
~~contacts_update-contact~~-更新联系人 （残疾）
~~contacts_upsert-contact~~-创建或更新联系人 （残疾）
~~contacts_add-tags~~-为联系人添加标签 （残疾）
~~contacts_remove-tags~~-从联系人中删除标签 （残疾）

对话（2个活动，1个禁用）

conversations_search-conversation -搜索对话
conversations_get-messages -获取对话消息
~~conversations_send-a-new-message~-发送短信/电子邮件/WhatsApp （残疾）

机会（3个有效，1个无效）

opportunities_search-opportunity -搜索机会
opportunities_get-opportunity -获取机会详细信息
opportunities_get-pipelines -获取所有管道
~~opportunities_update-opportunity~~-更新机会 （残疾）

日历（4工具）

get-calendars -列出某个位置的所有日历（发现日历ID）
calendars_get-calendars -与 get-calendars （规范名称）
calendars_get-calendar-events -获取日历事件；否时自动发现所有日历 calendarId/userId/groupId 提供
calendars_get-appointment-notes -获取预约记录

位置（2个工具）

locations_get-location -获取位置详细信息
locations_get-custom-fields -获取自定义字段

付款（2个工具）

payments_get-order-by-id -获取付款单
payments_list-transactions -列出交易记录

实用工具（2个工具）

cache_get-stats -获取用于调试的缓存统计信息
list_clients -列出所有可用的客户端名称

先决条件

Node.js 18+（用于本地开发）
Cloudflare Workers帐户
使用高级OAuth令牌的Supabase帐户
TypingMind、ClickUp Brain或其他兼容MCP的客户端

数据库模式

您的Supabase数据库必须包含以下表：

locations 表：

CREATE TABLE locations (
  location_id TEXT PRIMARY KEY,
  access_token TEXT NOT NULL,
  refresh_token TEXT,
  company_id TEXT,
  location_name TEXT,
  created_at TIMESTAMP DEFAULT NOW(),
  updated_at TIMESTAMP DEFAULT NOW()
);

master_clients 表（可选，用于客户端名称查找）：

CREATE TABLE master_clients (
  id SERIAL PRIMARY KEY,
  client_name TEXT UNIQUE NOT NULL,
  location_id TEXT REFERENCES locations(location_id),
  created_at TIMESTAMP DEFAULT NOW()
);

安装

1.克隆存储库

git clone https://github.com/isaganiesteron/highlevel-mcp-server.git
cd highlevel-mcp-server

2.安装依赖项

npm install

3.配置环境变量

复制 wrangler.jsonc.example 到 wrangler.jsonc 并创建一个 .dev.vars 本地开发文件：

API_KEY=your-secure-api-key
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_SERVICE_KEY=eyJhbGc...your-service-key
HIGHLEVEL_API_BASE=https://services.leadconnectorhq.com
TOKEN_CACHE_TTL=300000
CLIENT_CACHE_TTL=600000

对于制作，通过牧马人设置秘密（不要将秘密提交给 wrangler.jsonc):

wrangler secret put API_KEY
wrangler secret put SUPABASE_URL
wrangler secret put SUPABASE_SERVICE_KEY

发展

本地开发

npm run dev

服务器将于启动 http://localhost:8787

MCP检验员测试

npx @modelcontextprotocol/inspector node dist/index.js

运行测试

npm test

部署

部署到Cloudflare Workers

# Production deployment
npm run deploy

# Or using wrangler directly
wrangler deploy

配置机密

wrangler secret put API_KEY
wrangler secret put SUPABASE_URL
wrangler secret put SUPABASE_SERVICE_KEY

验证部署

curl https://your-worker.workers.dev/

预期响应：

{
  "name": "HighLevel CRM Multi-Account MCP Server",
  "version": "1.0.2",
  "status": "running",
  "toolCount": 18,
  "calendarTools": ["calendars_get-calendars", "get-calendars", "calendars_get-calendar-events", "calendars_get-appointment-notes"],
  "endpoints": { "sse": "/sse", "mcp": "/mcp" }
}

用法

在ClickUp Brain中配置（流式HTTP）

网址： https://your-worker.workers.dev/mcp
认证： X-API-Key 带有API密钥的标头

连接后，如果工具未出现，则断开连接并重新连接——客户端缓存来自的工具列表 tools/list.

在TypingMind中配置（传统SSE）

添加到您的TypingMind MCP配置中：

{
	"mcpServers": {
		"highlevel": {
			"url": "https://your-worker.workers.dev/sse",
			"transport": "sse",
			"name": "HighLevel CRM (All Clients)"
		}
	}
}

查询示例

列出可用客户端：

User: "What HighLevel clients are available?"

发现日历，然后获取事件：

User: "Pull Bear Construction's calendar events for this week"

AI将呼叫 get-calendars （或 calendars_get-calendar-events 使用自动发现），然后获取该日期范围内的事件。

多账户审计：

User: "Check all GHL clients with no bookings this month"

AI迭代客户端，发现日历，并汇总跨帐户的预订计数。

使用客户端名称：

User: "Get all contacts for ABC Remodeling"

使用位置ID:

User: "Get location details for LN27DIXpeAMiwdjXhDZw"

演出

平均响应时间： <800ms（缓存命中率<500ms）
缓存命中率： >预热后80%
令牌缓存TTL： 5分钟
客户端映射缓存： 10分钟
并发请求： 支持100+个请求/分钟

缓存策略

令牌缓存：

访问令牌在内存中缓存5分钟
将Supabase查询减少80%+
缓存是针对每个工作实例的（Cloudflare自动扩展）

客户端名称映射：

clientName → locationId 缓存10分钟
小数据集（32个客户端），可安全缓存更长时间

错误处理

服务器提供用户友好的错误消息：

"Client 'ABC Remodeling' not found" -客户端名称无效
"No access token for location LN27DIXpeAMiwdjXhDZw" -缺少/无效令牌
"Contact not found" -联系人ID无效
"HighLevel API rate limit exceeded" -达到速率限制
"HighLevel API temporarily unavailable" -API下降

生产调试

为以下对象生成结构化JSON日志 wrangler tail:

wrangler tail

关键日志事件： request.received, route.matched, mcp.method.parsed, mcp.tools.call, mcp.response.sent, mcp.session.created, auth.failed.

故障排除

问题：“找不到会话”（ClickUp/Streamable HTTP）

原因： 客户端正在使用过时的工具列表或旧的服务器版本。

修复：

验证健康检查是否显示最新 version 和 toolCount
在ClickUp中断开和重新连接MCP集成
确保您正在使用 POST /mcp，不 /sse

问题：“没有日历”或缺少日历ID

修复：

使用 get-calendars 或 calendars_get-calendars 列出日历ID
或致电 calendars_get-calendar-events 只有 startTime/endTime --它会自动发现所有日历

问题：“位置没有访问令牌”

检查：

Supabase中存在令牌 locations 桌子
令牌不是空字符串
location_id 完全匹配

修复：

通过高级OAuth流重新验证客户端
在Supabase中验证令牌

问题：“401未经高级API授权”

检查：

访问令牌有效（未过期）

修复：

使用现有OAuth基础架构刷新令牌
注意：此MCP服务器不刷新令牌（对Supabase的只读访问）

问题：“未找到客户端”

检查：

客户端存在于 master_clients 桌子
client_name 拼写准确（区分大小写）

修复：

将客户端添加到 master_clients 桌子
使用 locationId 直接代替

问题：响应时间慢

检查：

缓存命中率（预热后应>80%）
高级API延迟（外部依赖）
Supabase查询性能

修复：

增加 TOKEN_CACHE_TTL 如有需要
检查Cloudflare Workers分析
监控Supabase性能

安全

认证

用于高级API的OAuth 2.0访问令牌
存储为Cloudflare机密的Supabase服务密钥
日志或错误消息中没有暴露的令牌

数据隐私

MCP服务器未存储数据（仅传递）
令牌缓存仅在内存中（5分钟TTL）
日志不包含PII

合规

GDPR：数据最小化（无不必要的存储）
CCPA：尊重用户数据权利
SOC 2:Cloudflare和Supabase符合SOC 2标准

监控

Cloudflare员工分析

请求计数和延迟
错误率
地理分布

建议的额外监测

错误跟踪哨兵
缓存命中率的自定义指标
错误率峰值警报

项目结构

highlevel-mcp-server/
├── src/
│   ├── index.ts                 # MCP server, tool definitions, routing
│   └── lib/
│       ├── supabase.ts          # Supabase client
│       ├── token-manager.ts     # Token caching logic
│       ├── highlevel-client.ts  # HighLevel API client
│       ├── client-resolver.ts   # Client name → location ID
│       └── response-formatter.ts # Human-readable tool output
├── test/
│   └── index.spec.ts
├── postman/                     # API test collections
├── wrangler.jsonc.example       # Cloudflare Workers config template
├── package.json
├── tsconfig.json
└── README.md

贡献

欢迎投稿！请遵循以下指南：

分叉存储库
创建要素分支(git checkout -b feature/amazing-feature)
提交您的更改(git commit -m 'Add amazing feature')
推到分支(git push origin feature/amazing-feature)
打开拉取请求

发展路线图

第一阶段：基础✅

[x] 项目设置和架构
[x] 使用缓存进行令牌管理
[x] 客户端标识符解析器
[x] 错误处理框架

第二阶段：工具实施✅

[x] 18个只读工具模式（源代码中禁用了12个写操作）
[x] 高层API端点映射
[x] 请求/响应格式
[x] 日历发现工具(get-calendars，事件中的自动发现）

第三阶段：运输和生产✅

[x] 可流式HTTP传输(POST /mcp)
[x] 保留了传统的SSE传输(/sse)
[x] Cloudflare Workers的无状态会话处理
[x] 结构化 wrangler tail 日志
[x] ClickUp Brain集成测试
[x] 生产部署

未来的增强功能

[]MCP服务器内的自动令牌刷新
[]高级webhook支持（实时事件）
[]读取操作的响应缓存
[]请求批量操作的批处理
[]缓存检查管理界面
[]工作流自动化模板

许可证

MIT许可证-请参阅许可证详细信息文件

支持

问题： GitHub问题
讨论： GitHub讨论
电子邮件： isagani@contractorscale.com

致谢

内置于模型上下文协议
由...驱动 Cloudflare员工
数据库按 Supabase
与集成高级
模板基于 typingmind mcp cloudflare启动器

使用说明

高级MCP服务器

概述

主要特点

为什么存在

建筑

端点

可用工具（18个只读）

联系人（3个活动，5个禁用）

对话（2个活动，1个禁用）

机会（3个有效，1个无效）

日历（4工具）

位置（2个工具）

付款（2个工具）

实用工具（2个工具）

先决条件

数据库模式

安装

1.克隆存储库

2.安装依赖项

3.配置环境变量

发展

本地开发

MCP检验员测试

运行测试

部署

部署到Cloudflare Workers

配置机密

验证部署

用法

在ClickUp Brain中配置（流式HTTP）

在TypingMind中配置（传统SSE）

查询示例

演出

缓存策略

错误处理

生产调试

故障排除

问题：“找不到会话”（ClickUp/Streamable HTTP）

问题：“没有日历”或缺少日历ID

问题：“位置没有访问令牌”

问题：“401未经高级API授权”

问题：“未找到客户端”

问题：响应时间慢

安全

认证

数据隐私

合规

监控

Cloudflare员工分析

建议的额外监测

项目结构

贡献

发展路线图

第一阶段：基础✅

第二阶段：工具实施✅

第三阶段：运输和生产✅

未来的增强功能

许可证

支持

致谢

相关项目

相关 MCP

Telegram MCP 服务

邮件管理MCP服务器

CRM管理服务器

Attio CRM MCP 服务器

Google Workspace MCP服务器

摄像头管理系统