hubspot-automation

通过 Rube MCP 自动化 HubSpot CRM

通过 Composio 的 HubSpot 工具包自动化 HubSpot CRM 工作流，包括联系人／公司管理、交易管道跟踪、工单搜索和自定义属性创建。

工具包文档：composio.dev/toolkits/hubspot

前置条件

• 必须连接 Rube MCP（可用 RUBE_SEARCH_TOOLS）
• 通过工具包为 hubspot 的 RUBE_MANAGE_CONNECTIONS 建立有效的 HubSpot 连接
• 始终先调用 RUBE_SEARCH_TOOLS 以获取当前工具架构

设置

获取 Rube MCP：在客户端配置中将 https://rube.app/mcp 添加为 MCP 服务。无需 API 密钥，只需添加端点即可使用。

1. 确认 RUBE_SEARCH_TOOLS 有响应，以验证 Rube MCP 是否可用
2. 调用工具包为 hubspot 的 RUBE_MANAGE_CONNECTIONS
3. 如果连接状态不是 ACTIVE，请按照返回的授权链接完成 HubSpot OAuth
4. 在运行任何工作流前，确认连接状态显示为 ACTIVE

核心工作流

1. 创建和管理联系人

适用场景：用户想在 HubSpot CRM 中创建联系人或更新现有联系人

工具调用顺序：

1. HUBSPOT_GET_ACCOUNT_INFO - 验证连接和权限（前置条件）
2. HUBSPOT_SEARCH_CONTACTS_BY_CRITERIA - 搜索现有联系人以避免重复（前置条件）
3. HUBSPOT_READ_A_CRM_PROPERTY_BY_NAME - 检查受限值的属性元数据（可选）
4. HUBSPOT_CREATE_CONTACT - 创建单个联系人（必需）
5. HUBSPOT_CREATE_CONTACTS - 批量创建联系人，最多 100 个（替代方案）

关键参数：

• HUBSPOT_CREATE_CONTACT：包含 email、firstname、lastname、phone、company 的 properties 对象
• HUBSPOT_CREATE_CONTACTS：由 {properties} 对象组成的 inputs 数组，每批最多 100 个
• HUBSPOT_SEARCH_CONTACTS_BY_CRITERIA：包含 {filters: [{propertyName, operator, value}]} 的 filterGroups 数组，以及要返回字段的 properties 数组

注意事项：

• 每批最多 100 条记录；较大的导入任务应分批处理
• 如果使用了错误的属性名称或枚举值，会出现 400 'Property values were not valid' 错误
• 创建前务必先搜索，以避免重复
• GET_ACCOUNT_INFO 出现身份验证错误，意味着后续所有调用都会失败

2. 管理公司

适用场景：用户想创建、搜索或更新公司记录

工具调用顺序：

1. HUBSPOT_SEARCH_COMPANIES - 搜索现有公司（前置条件）
2. HUBSPOT_CREATE_COMPANIES - 批量创建公司，最多 100 个（必需）
3. HUBSPOT_UPDATE_COMPANIES - 批量更新现有公司（替代方案）
4. HUBSPOT_GET_COMPANY - 获取单个公司的详细信息（可选）
5. HUBSPOT_BATCH_READ_COMPANIES_BY_PROPERTIES - 根据属性值批量读取公司（可选）

关键参数：

• HUBSPOT_CREATE_COMPANIES：由 {properties} 对象组成的 inputs 数组，最多 100 个
• HUBSPOT_SEARCH_COMPANIES：filterGroups、properties、sorts、limit、after（分页游标）

注意事项：

• 每批最多 100 个；较大的数据集应分批处理
• 立即保存返回的 ID，以供后续操作使用
• 属性值必须与内部名称完全匹配，不能使用显示标签

3. 管理交易和销售管道

使用时机：用户想要搜索交易、查看销售管道阶段或跟踪交易进度

工具调用顺序：

1. HUBSPOT_RETRIEVE_ALL_PIPELINES_FOR_SPECIFIED_OBJECT_TYPE - 映射销售管道和阶段的 ID/名称（前置条件）
2. HUBSPOT_SEARCH_DEALS - 使用筛选条件搜索交易（必需）
3. HUBSPOT_RETRIEVE_PIPELINE_STAGES - 获取某个销售管道的阶段详情（可选）
4. HUBSPOT_RETRIEVE_OWNERS - 获取负责人/销售代表详情（可选）
5. HUBSPOT_GET_DEAL - 获取单笔交易详情（可选）
6. HUBSPOT_LIST_DEALS - 不使用筛选条件列出所有交易（备用方案）

关键参数：

• HUBSPOT_SEARCH_DEALS：使用 filterGroups 按 pipeline、dealstage、createdate、closedate、hubspot_owner_id 筛选；以及 properties、sorts、limit、after
• HUBSPOT_RETRIEVE_ALL_PIPELINES_FOR_SPECIFIED_OBJECT_TYPE：将 objectType 设为 'deals'

注意事项：

• 结果嵌套在 response.data.results 下；属性通常是字符串（金额、日期）
• 阶段 ID 可能是可读字符串，也可能是不透明的数字 ID；显示时使用 label 字段
• 筛选条件必须使用内部属性名称（pipeline、dealstage、createdate），而非显示名称
• 通过 paging.next.after 翻页，直到该字段不存在

4. 搜索和筛选工单

使用时机：用户想要按状态、日期或条件查找支持工单

工具调用顺序：

1. HUBSPOT_SEARCH_TICKETS - 使用 filterGroups 搜索（必需）
2. HUBSPOT_READ_ALL_PROPERTIES_FOR_OBJECT_TYPE - 查找可用的属性名称（备用方案）
3. HUBSPOT_GET_TICKET - 获取单个工单详情（可选）
4. HUBSPOT_GET_TICKETS - 按 ID 批量获取工单（可选）

关键参数：

• HUBSPOT_SEARCH_TICKETS：filterGroups、properties（仅返回列出的字段）、sorts、limit、after

注意事项：

• 错误的 propertyName/operator 会导致结果为零，且不会报错
• 日期筛选可能需要使用 epoch 毫秒边界；混用不同格式会导致不匹配
• 仅返回 properties 数组中的字段；缺少字段会导致下游逻辑出错
• 使用 READ_ALL_PROPERTIES 查找准确的内部属性名称

5. 创建和管理自定义属性

使用时机：用户想要为 CRM 对象添加自定义字段

工具调用顺序：

1. HUBSPOT_READ_ALL_PROPERTIES_FOR_OBJECT_TYPE - 列出现有属性（前置条件）
2. HUBSPOT_READ_PROPERTY_GROUPS_FOR_OBJECT_TYPE - 列出属性组（可选）
3. HUBSPOT_CREATE_PROPERTY_FOR_SPECIFIED_OBJECT_TYPE - 创建单个属性（必需）
4. HUBSPOT_CREATE_BATCH_OF_PROPERTIES - 批量创建属性（替代方案）
5. HUBSPOT_UPDATE_SPECIFIC_CRM_PROPERTY - 更新现有属性定义（可选）

关键参数：

• HUBSPOT_CREATE_PROPERTY_FOR_SPECIFIED_OBJECT_TYPE：objectType、name、label、type（string/number/date/enumeration）、fieldType、groupName、options（用于枚举）

注意事项：

• 属性名称创建后不可更改；请谨慎选择
• 必须预先定义枚举选项的 value 和 label
• 将属性分配到某个组之前，该组必须已存在

常见模式

ID 解析

• 属性显示名称 → 内部名称：使用 HUBSPOT_READ_ALL_PROPERTIES_FOR_OBJECT_TYPE
• 销售管道名称 → 销售管道 ID：使用 HUBSPOT_RETRIEVE_ALL_PIPELINES_FOR_SPECIFIED_OBJECT_TYPE
• 阶段名称 → 阶段 ID：从销售管道阶段响应中提取
• 负责人名称 → 负责人 ID：使用 HUBSPOT_RETRIEVE_OWNERS

分页

• 搜索端点使用基于游标的分页
• 持续使用 paging.next.after 翻页，直到该字段不存在
• 典型限制：每页 100 条记录
• 将上一条响应中的 after 值传递给下一页请求

批量操作

• 大多数创建/更新端点都支持批量操作，每次调用最多 100 条记录
• 对于更大的数据集，分成每组 100 条
• 继续操作前，保存每批返回的 ID
• 为提高效率，请使用批量端点（CREATE_CONTACTS、CREATE_COMPANIES、UPDATE_COMPANIES），而非单条记录端点

已知注意事项

• 属性名称：所有搜索/筛选端点都使用内部属性名称，而非显示标签。务必调用 READ_ALL_PROPERTIES_FOR_OBJECT_TYPE 以查找正确的名称
• 批量限制：每次批量操作最多处理 100 条记录。更大的数据集必须拆分处理
• 响应结构：搜索结果位于 response.data.results 中，属性值为字符串
• 日期格式：日期属性可能是 epoch-ms 或 ISO 字符串，具体取决于端点。请采用稳妥的解析方式
• 名称不可变：创建后无法更改属性名称。请谨慎规划命名规范
• 游标分页：使用 paging.next.after 游标，而非页码。持续获取，直到 after 不存在
• 防止重复：创建联系人/公司前务必先搜索，以避免重复
• 身份验证检查：先运行 HUBSPOT_GET_ACCOUNT_INFO；身份验证失败会导致后续所有调用失败

快速参考

任务	工具 Slug	关键参数
创建联系人	HUBSPOT_CREATE_CONTACT	properties: {email, firstname, lastname}
批量创建联系人	HUBSPOT_CREATE_CONTACTS	inputs: [{properties}]（最多 100 条）
搜索联系人	HUBSPOT_SEARCH_CONTACTS_BY_CRITERIA	filterGroups, properties, limit, after
创建公司	HUBSPOT_CREATE_COMPANIES	inputs: [{properties}]（最多 100 条）
搜索公司	HUBSPOT_SEARCH_COMPANIES	filterGroups, properties, after
搜索交易	HUBSPOT_SEARCH_DEALS	filterGroups, properties, after
获取管道	HUBSPOT_RETRIEVE_ALL_PIPELINES_FOR_SPECIFIED_OBJECT_TYPE	objectType: 'deals'
搜索工单	HUBSPOT_SEARCH_TICKETS	filterGroups, properties, after
列出属性	HUBSPOT_READ_ALL_PROPERTIES_FOR_OBJECT_TYPE	objectType
创建属性	HUBSPOT_CREATE_PROPERTY_FOR_SPECIFIED_OBJECT_TYPE	objectType, name, label, type, fieldType
获取所有者	HUBSPOT_RETRIEVE_OWNERS	无
验证连接	HUBSPOT_GET_ACCOUNT_INFO	无

---

由 Composio 提供支持