AI导哈

HubSpot MCP服务器

为达到API限制的团队提供的HubSpot MCP服务器，提供去重合并计划、自动窗口突破限制、属性漂移检测和批量更新插入功能。

  • by mikeheilmann1024
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 mikeheilmann1024/g-gremlin-hubspot-mcp

使用说明

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.

  1. 安装mcporter：
npm install -g mcporter
  1. 在mcporter配置中添加此MCP服务器：
{
  "mcpServers": {
    "g-gremlin-hubspot": {
      "command": "g-gremlin-hubspot-mcp",
      "env": {
        "G_GREMLIN_HUBSPOT_ACCESS_TOKEN": "YOUR_TOKEN"
      }
    }
  }
}
  1. 使用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打破了这一点 递归日期范围窗口:

  1. 初始查询达到10k上限
  2. 检查 createdate 返回记录中的时间戳
  3. 将时间范围一分为二，重新查询每个窗口
  4. 递归重复（最大深度8，最小窗口7天）
  5. 按记录键跨窗口进行重复数据消除

必修的： 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万条记录并生成去重合并计划——无需帐户。当您对发现的内容采取行动时（追加销售、应用合并、快照），就会出现付费墙。

安全模型

所有突变都使用 两阶段确认:

  1. 试运行 （默认）：工具运行时不进行更改，返回预览+ plan_hash
  2. 应用：呼叫者通行证 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的证书链：

  1. G_GREMLIN_HUBSPOT_ACCESS_TOKEN env-var（最高优先级）
  2. g-gremlin hubspot connect --access-token <PAT> （存储在本地 ~/.g_gremlin/)
  3. 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

许可证

麻省理工学院

相关 MCP