g-gremlin-hubspot-mcp
状态：公测 --14款工具发货，核心工作流程稳定，欢迎反馈。看 已知差距 在......下面
HubSpot MCP服务器，适用于达到API上限的团队。
HubSpot的官方MCP为您提供只读搜索，最多可搜索10000条记录。此功能为您提供去重合并计划、超过上限的自动窗口、属性漂移检测和批量故障——所有这些都来自Claude Desktop、Cursor或Windsurf。
由...驱动 g-小精灵，用于Google Workspace和CRM自动化的CLI。
快速启动
# 1. Install
pipx install g-gremlin
pipx install g-gremlin-hubspot-mcp
# 2. Connect to HubSpot (one-time)
g-gremlin hubspot connect --access-token YOUR_PRIVATE_APP_TOKEN
# 3. Add to your MCP client克劳德桌面
添加到您的 claude_desktop_config.json:
{
"mcpServers": {
"g-gremlin-hubspot": {
"command": "g-gremlin-hubspot-mcp",
"env": {
"G_GREMLIN_HUBSPOT_ACCESS_TOKEN": "YOUR_TOKEN"
}
}
}
}光标/风帆
添加到MCP设置中：
{
"mcpServers": {
"g-gremlin-hubspot": {
"command": "g-gremlin-hubspot-mcp"
}
}
}OpenClaw（社区通过mcporter支持）
OpenClaw可以通过以下方式调用MCP服务器 mcporter.
- 安装mcporter：
npm install -g mcporter- 在mcporter配置中添加此MCP服务器：
{
"mcpServers": {
"g-gremlin-hubspot": {
"command": "g-gremlin-hubspot-mcp",
"env": {
"G_GREMLIN_HUBSPOT_ACCESS_TOKEN": "YOUR_TOKEN"
}
}
}
}- 使用OpenClaw和mcporter技能/运行时来列出和调用以下工具
g-gremlin-hubspot.
如何比较
| 能力 | HubSpot官方MCP | peakmojo/MCP HubSpot | g-gremlin-hubspot-mcp |
|---|---|---|---|
| CRM搜索 | 上限10k | 缓存/向量 | 自动车窗超过10k |
| 写入操作 | 否 | 仅创建 | 起床+干跑 |
| 重复检测 | 否 | 否 | 合并计划 |
| 模式自省 | 否 | 否 | 完整的架构/道具 |
| 订婚导出 | 否 | 否 | 异步回退 |
| 快照差异 | 否 | 否 | 是 |
| 安全层 | N/A | 无 | 模拟运行+计划哈希 |
| 影响分类 | 否 | 否 | 每个工具标签 |
我们如何打破10k的上限
HubSpot的搜索API有10000个总结果的硬性上限，除此之外没有光标。
g-gremlin打破了这一点 递归日期范围窗口:
- 初始查询达到10k上限
- 检查
createdate返回记录中的时间戳 - 将时间范围一分为二，重新查询每个窗口
- 递归重复（最大深度8，最小窗口7天）
- 按记录键跨窗口进行重复数据消除
必修的： createdate （默认）或任何可排序的日期属性。对于没有时间戳的对象，参与使用没有上限的异步导出回退。
可用工具
7个工具无需帐户即可使用（免费）。7需要g-gremlin HubSpot管理员许可证或主动试用。 首次安装时提供30天试用期。
第1层：阅读与发现
| 工具 | 影响 | 许可证 | 它的作用 |
|---|---|---|---|
hubspot.auth.whoami | [READ] | 免费 | 检查身份验证，显示门户身份 |
hubspot.auth.doctor | [READ] | 许可 | 运行状况诊断（连接、作用域、API访问） |
hubspot.schema.list | [READ] | 免费 | 列出所有CRM对象类型（标准+自定义） |
hubspot.schema.get | [READ] | FREE | 对象类型的完整架构（属性、关联） |
hubspot.props.list | [READ] | 许可 | 财产自省（名称、类型、标签） |
hubspot.objects.query | [READ] | 免费 | 带过滤器的CRM搜索（搜索API，上限为10k） |
hubspot.objects.pull | [READ] | 免费 | 超过10k天花板的完全提取（自动开窗） |
hubspot.engagements.pull | [READ] | 免费 | 使用异步导出回退进行参与拉取 |
第2层：分析和计划
| 工具 | 影响 | 许可证 | 它的作用 |
|---|---|---|---|
hubspot.dedupe.plan | [ANALYZE] | 免费 | 扫描重复项，使用plan_hash生成合并计划 |
hubspot.props.drift | [ANALYZE] | 许可 | 检测规范和实时门户之间的属性漂移 |
hubspot.snapshot.create | [READ] | 许可 | 捕获CRM状态（模式、道具、计数） |
hubspot.snapshot.diff | [ANALYZE] | 许可 | 比较两个快照，显示更改的内容 |
第3级：突变
| 工具 | 影响 | 许可证 | 它的作用 |
|---|---|---|---|
hubspot.objects.upsert | [WRITE] | 许可 | 从CSV批量追加销售（模拟运行默认，两阶段应用） |
hubspot.dedupe.apply | [MERGE] | 许可 | 执行合并计划（需要plan_hash验证） |
免费工具是最强的钩子： 提取过去1万条记录并生成去重合并计划——无需帐户。当您对发现的内容采取行动时（追加销售、应用合并、快照），就会出现付费墙。
安全模型
所有突变都使用 两阶段确认:
- 试运行 （默认）：工具运行时不进行更改，返回预览+
plan_hash - 应用：呼叫者通行证
apply=true以及plan_hash从步骤1开始。如果哈希值不匹配（计划更改、文件错误），该工具将以明显的错误拒绝。
每个工具响应都包括影响分类： [READ], [ANALYZE], [WRITE]，或 [MERGE].
响应信封
每个工具都返回一致的 GremlinMCPResponse/v1 JSON：
{
"$schema": "GremlinMCPResponse/v1",
"ok": true,
"summary": "Pulled 47,231 contacts across 12 auto-window queries",
"data": { ... },
"artifact": { "type": "file", "path": "...", "row_count": 47231 },
"warnings": [],
"safety": { "dry_run": false, "impact": "read" },
"raw": { "agentic_result": { ... }, "exit_code": 0 }
}认证
此MCP服务器 从不存储令牌。它委托给g-gremlin的证书链：
G_GREMLIN_HUBSPOT_ACCESS_TOKENenv-var（最高优先级）- `g-gremlin hubspot connect --access-token
（存储在本地 ~/.g_gremlin/`)
g-gremlin hubspot oauth connect（基于浏览器的OAuth）
故障排除
Claude Desktop中出现“HubSpot未配置”错误？
Claude Desktop可能在与您的终端不同的用户上下文下运行。在MCP配置中设置令牌 env 块（见上面的快速启动）或设置 G_GREMLIN_HUBSPOT_ACCESS_TOKEN 作为系统级环境变量。
已知差距和路线图
这是一个 公开测试版核心读取和分析工作流程稳定。已知差距：
- 远程MCP（SSE传输） --目前仅限stdio；计划为不希望本地安装的团队提供SSE/流式HTTP
- 工作流程差异 --g-gremlin具有工作流比较命令，尚未作为MCP工具公开
- 协会管理 --创建/删除对象之间的关联
- 列表管理 --HubSpot列表创建和会员管理
- 管道管理 --交易/票务管道配置
发现错误或有功能请求？ 打开一个问题.
需要
- Python 3.10+
- g-gremlin>=0.1.14（启动时检查版本）
- 具有CRM作用域的HubSpot专用应用令牌
发展
git clone https://github.com/mikeheilmann1024/g-gremlin-hubspot-mcp
cd g-gremlin-hubspot-mcp
pip install -e ".[dev]"
pytest许可证
麻省理工学院