hubspot-automation

通过 Rube MCP 实现 HubSpot CRM 自动化

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

先决条件

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

设置

获取 Rube MCP：在客户端配置中将 https://rube.app/mcp 添加为 MCP 服务。目标 HubSpot 账户仍须完成返回的身份验证流程并授予所需的权限范围。

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

账户、架构和写入权限范围

在使用这些历史 slug/参数示例之前，先确定确切的账户并检查当前架构。创建前先搜索可减少重复记录，但不能保证在并发情况下唯一：请使用受支持的唯一 ID/upsert 语义，并在重试前核实结果不确定的写入。限制返回的联系人字段，对日志中的个人数据进行脱敏，预览批次大小和目标，并保留部分失败结果。创建 CRM 记录、分配记录、更改属性架构和进行外联都需要相应的用户权限；读取请求不会授予这些写入权限。

核心工作流

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}] (max 100)
搜索联系人	HUBSPOT_SEARCH_CONTACTS_BY_CRITERIA	filterGroups, properties, limit, after
创建公司	HUBSPOT_CREATE_COMPANIES	inputs: [{properties}] (max 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	无

何时使用

此技能适用于执行概述中描述的工作流或操作。

示例

用户请求：

通过 Rube MCP 使用 Composio 集成自动化 HubSpot CRM 操作（联系人、公司、交易、工单、属性）。

限制

• 仅当任务明确符合上述范围时才使用此技能。
• 请勿将输出视为环境特定验证、测试或专家审查的替代品。
• 如果缺少必需的输入、权限、安全边界或成功标准，请停止并请求澄清。