hubspot-automation

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

HubSpot CRM Automation via Rube MCP

借助Rube MCP实现HubSpot CRM自动化

Automate HubSpot CRM workflows including contact/company management, deal pipeline tracking, ticket search, and custom property creation through Composio's HubSpot toolkit.

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

Prerequisites

前提条件

Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
Active HubSpot connection via
```
RUBE_MANAGE_CONNECTIONS
```
with toolkit
```
hubspot
```
Always call
```
RUBE_SEARCH_TOOLS
```
first to get current tool schemas

必须已连接Rube MCP（需有RUBE_SEARCH_TOOLS可用）
通过
```
RUBE_MANAGE_CONNECTIONS
```
并使用工具包
```
hubspot
```
建立HubSpot活跃连接
始终先调用
```
RUBE_SEARCH_TOOLS
```
获取当前工具架构

Setup

设置步骤

Get Rube MCP: Add

https://rube.app/mcp

as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.

Verify Rube MCP is available by confirming
```
RUBE_SEARCH_TOOLS
```
responds
Call
```
RUBE_MANAGE_CONNECTIONS
```
with toolkit
```
hubspot
```
If connection is not ACTIVE, follow the returned auth link to complete HubSpot OAuth
Confirm connection status shows ACTIVE before running any workflows

获取Rube MCP：在客户端配置中添加

https://rube.app/mcp

作为MCP服务器。无需API密钥 — 只需添加端点即可使用。

通过确认
```
RUBE_SEARCH_TOOLS
```
能响应，验证Rube MCP是否可用
调用
```
RUBE_MANAGE_CONNECTIONS
```
并指定工具包
```
hubspot
```
如果连接状态不是ACTIVE，按照返回的授权链接完成HubSpot OAuth认证
在运行任何工作流之前，确认连接状态显示为ACTIVE

Core Workflows

核心工作流

1. Create and Manage Contacts

1. 创建与管理联系人

When to use: User wants to create new contacts or update existing ones in HubSpot CRM

Tool sequence:

```
HUBSPOT_GET_ACCOUNT_INFO
```
- Verify connection and permissions (Prerequisite)
```
HUBSPOT_SEARCH_CONTACTS_BY_CRITERIA
```
- Search for existing contacts to avoid duplicates (Prerequisite)
```
HUBSPOT_READ_A_CRM_PROPERTY_BY_NAME
```
- Check property metadata for constrained values (Optional)
```
HUBSPOT_CREATE_CONTACT
```
- Create a single contact (Required)
```
HUBSPOT_CREATE_CONTACTS
```
- Batch create contacts up to 100 (Alternative)

Key parameters:

HUBSPOT_CREATE_CONTACT

properties

object with

email

firstname

lastname

phone

company

HUBSPOT_CREATE_CONTACTS

inputs

array of

{properties}

objects, max 100 per batch

HUBSPOT_SEARCH_CONTACTS_BY_CRITERIA

filterGroups

array with

{filters: [{propertyName, operator, value}]}

properties

array of fields to return

Pitfalls:

Max 100 records per batch; chunk larger imports
400 'Property values were not valid' if using incorrect property names or enum values
Always search before creating to avoid duplicates
Auth errors from GET_ACCOUNT_INFO mean all subsequent calls will fail

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

工具调用序列:

```
HUBSPOT_GET_ACCOUNT_INFO
```
- 验证连接与权限（前提步骤）
```
HUBSPOT_SEARCH_CONTACTS_BY_CRITERIA
```
- 搜索现有联系人以避免重复（前提步骤）
```
HUBSPOT_READ_A_CRM_PROPERTY_BY_NAME
```
- 检查属性元数据的约束值（可选）
```
HUBSPOT_CREATE_CONTACT
```
- 创建单个联系人（必填步骤）
```
HUBSPOT_CREATE_CONTACTS
```
- 批量创建最多100个联系人（替代方案）

关键参数:

HUBSPOT_CREATE_CONTACT

properties

对象，包含

email

、

firstname

、

lastname

、

phone

、

company

```
HUBSPOT_CREATE_CONTACTS
```
:
```
inputs
```
数组，每个元素为
```
{properties}
```
对象，每批最多100个

HUBSPOT_SEARCH_CONTACTS_BY_CRITERIA

filterGroups

数组，包含

{filters: [{propertyName, operator, value}]}

，

properties

数组为需返回的字段

注意事项:

每批最多100条记录；若导入数据量更大，需拆分处理
若使用错误的属性名称或枚举值，会返回400错误“Property values were not valid”
创建前务必先搜索，避免重复
若
```
GET_ACCOUNT_INFO
```
返回认证错误，后续所有调用都会失败

2. Manage Companies

2. 管理公司记录

When to use: User wants to create, search, or update company records

Tool sequence:

```
HUBSPOT_SEARCH_COMPANIES
```
- Search existing companies (Prerequisite)
```
HUBSPOT_CREATE_COMPANIES
```
- Batch create companies, max 100 (Required)
```
HUBSPOT_UPDATE_COMPANIES
```
- Batch update existing companies (Alternative)
```
HUBSPOT_GET_COMPANY
```
- Get single company details (Optional)
```
HUBSPOT_BATCH_READ_COMPANIES_BY_PROPERTIES
```
- Bulk read companies by property values (Optional)

Key parameters:

HUBSPOT_CREATE_COMPANIES

inputs

array of

{properties}

objects, max 100

HUBSPOT_SEARCH_COMPANIES

filterGroups

properties

sorts

limit

after

(pagination cursor)

Pitfalls:

Max 100 per batch; chunk larger sets
Store returned IDs immediately for downstream operations
Property values must match exact internal names, not display labels

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

工具调用序列:

```
HUBSPOT_SEARCH_COMPANIES
```
- 搜索现有公司（前提步骤）
```
HUBSPOT_CREATE_COMPANIES
```
- 批量创建公司，最多100个（必填步骤）
```
HUBSPOT_UPDATE_COMPANIES
```
- 批量更新现有公司（替代方案）
```
HUBSPOT_GET_COMPANY
```
- 获取单个公司详情（可选）
```
HUBSPOT_BATCH_READ_COMPANIES_BY_PROPERTIES
```
- 根据属性值批量读取公司（可选）

关键参数:

```
HUBSPOT_CREATE_COMPANIES
```
:
```
inputs
```
数组，每个元素为
```
{properties}
```
对象，最多100个

HUBSPOT_SEARCH_COMPANIES

filterGroups

、

properties

、

sorts

、

limit

、

after

（分页游标）

注意事项:

每批最多100条记录；若数据量更大，需拆分处理
立即存储返回的ID，用于后续操作
属性值必须与内部名称完全匹配，而非显示标签

3. Manage Deals and Pipeline

3. 管理交易与管道

When to use: User wants to search deals, view pipeline stages, or track deal progress

Tool sequence:

HUBSPOT_RETRIEVE_ALL_PIPELINES_FOR_SPECIFIED_OBJECT_TYPE

- Map pipeline and stage IDs/names (Prerequisite)

```
HUBSPOT_SEARCH_DEALS
```
- Search deals with filters (Required)
```
HUBSPOT_RETRIEVE_PIPELINE_STAGES
```
- Get stage details for one pipeline (Optional)
```
HUBSPOT_RETRIEVE_OWNERS
```
- Get owner/rep details (Optional)
```
HUBSPOT_GET_DEAL
```
- Get single deal details (Optional)
```
HUBSPOT_LIST_DEALS
```
- List all deals without filters (Fallback)

Key parameters:

HUBSPOT_SEARCH_DEALS

filterGroups

with filters on

pipeline

dealstage

createdate

closedate

hubspot_owner_id

;

properties

sorts

limit

after

HUBSPOT_RETRIEVE_ALL_PIPELINES_FOR_SPECIFIED_OBJECT_TYPE

objectType

set to

'deals'

Pitfalls:

Results nested under
```
response.data.results
```
; properties are often strings (amounts, dates)
Stage IDs may be readable strings or opaque numeric IDs; use
```
label
```
field for display
Filters must use internal property names (
```
pipeline
```
,
```
dealstage
```
,
```
createdate
```
), not display names
Paginate via
```
paging.next.after
```
until absent

适用场景：用户希望搜索交易、查看管道阶段或跟踪交易进度

工具调用序列:

HUBSPOT_RETRIEVE_ALL_PIPELINES_FOR_SPECIFIED_OBJECT_TYPE

- 映射管道与阶段的ID/名称（前提步骤）

```
HUBSPOT_SEARCH_DEALS
```
- 使用筛选条件搜索交易（必填步骤）
```
HUBSPOT_RETRIEVE_PIPELINE_STAGES
```
- 获取单个管道的阶段详情（可选）
```
HUBSPOT_RETRIEVE_OWNERS
```
- 获取负责人/销售代表详情（可选）
```
HUBSPOT_GET_DEAL
```
- 获取单个交易详情（可选）
```
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. Search and Filter Tickets

4. 搜索与筛选工单

When to use: User wants to find support tickets by status, date, or criteria

Tool sequence:

```
HUBSPOT_SEARCH_TICKETS
```
- Search with filterGroups (Required)
```
HUBSPOT_READ_ALL_PROPERTIES_FOR_OBJECT_TYPE
```
- Discover available property names (Fallback)
```
HUBSPOT_GET_TICKET
```
- Get single ticket details (Optional)
```
HUBSPOT_GET_TICKETS
```
- Bulk fetch tickets by IDs (Optional)

Key parameters:

HUBSPOT_SEARCH_TICKETS

filterGroups

properties

(only listed fields are returned),

sorts

limit

after

Pitfalls:

Incorrect
```
propertyName
```
/
```
operator
```
returns zero results without errors
Date filtering may require epoch-ms bounds; mixing formats causes mismatches
Only fields in the
```
properties
```
array are returned; missing ones break downstream logic
Use READ_ALL_PROPERTIES to discover exact internal property names

适用场景：用户希望按状态、日期或其他条件查找支持工单

工具调用序列:

```
HUBSPOT_SEARCH_TICKETS
```
- 使用filterGroups进行搜索（必填步骤）
```
HUBSPOT_READ_ALL_PROPERTIES_FOR_OBJECT_TYPE
```
- 发现可用的属性名称（备选方案）
```
HUBSPOT_GET_TICKET
```
- 获取单个工单详情（可选）
```
HUBSPOT_GET_TICKETS
```
- 根据ID批量获取工单（可选）

关键参数:

HUBSPOT_SEARCH_TICKETS

filterGroups

、

properties

（仅返回列出的字段）、

sorts

、

limit

、

after

注意事项:

若
```
propertyName
```
/
```
operator
```
不正确，会返回空结果且无错误提示
日期筛选可能需要毫秒级时间戳范围；混合格式会导致匹配失败
仅返回
```
properties
```
数组中的字段；缺失字段会破坏后续逻辑
使用
```
READ_ALL_PROPERTIES
```
来获取准确的内部属性名称

5. Create and Manage Custom Properties

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

When to use: User wants to add custom fields to CRM objects

Tool sequence:

HUBSPOT_READ_ALL_PROPERTIES_FOR_OBJECT_TYPE

- List existing properties (Prerequisite)

HUBSPOT_READ_PROPERTY_GROUPS_FOR_OBJECT_TYPE

- List property groups (Optional)

HUBSPOT_CREATE_PROPERTY_FOR_SPECIFIED_OBJECT_TYPE

- Create a single property (Required)

```
HUBSPOT_CREATE_BATCH_OF_PROPERTIES
```
- Batch create properties (Alternative)
```
HUBSPOT_UPDATE_SPECIFIC_CRM_PROPERTY
```
- Update existing property definition (Optional)

Key parameters:

HUBSPOT_CREATE_PROPERTY_FOR_SPECIFIED_OBJECT_TYPE

objectType

name

label

type

(string/number/date/enumeration),

fieldType

groupName

options

(for enumerations)

Pitfalls:

Property names are immutable after creation; choose carefully
Enumeration options must be pre-defined with
```
value
```
and
```
label
```
Group must exist before assigning properties to it

适用场景：用户希望为CRM对象添加自定义字段

工具调用序列:

HUBSPOT_READ_ALL_PROPERTIES_FOR_OBJECT_TYPE

- 列出现有属性（前提步骤）

HUBSPOT_READ_PROPERTY_GROUPS_FOR_OBJECT_TYPE

- 列出属性分组（可选）

HUBSPOT_CREATE_PROPERTY_FOR_SPECIFIED_OBJECT_TYPE

- 创建单个属性（必填步骤）

```
HUBSPOT_CREATE_BATCH_OF_PROPERTIES
```
- 批量创建属性（替代方案）
```
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
```
分配属性到分组前，分组必须已存在

Common Patterns

通用模式

ID Resolution

ID解析

Property display name → internal name: Use
```
HUBSPOT_READ_ALL_PROPERTIES_FOR_OBJECT_TYPE
```

Pipeline name → pipeline ID: Use

HUBSPOT_RETRIEVE_ALL_PIPELINES_FOR_SPECIFIED_OBJECT_TYPE

Stage name → stage ID: Extract from pipeline stages response
Owner name → owner ID: Use
```
HUBSPOT_RETRIEVE_OWNERS
```

属性显示名称 → 内部名称: 使用

HUBSPOT_READ_ALL_PROPERTIES_FOR_OBJECT_TYPE

管道名称 → 管道ID: 使用

HUBSPOT_RETRIEVE_ALL_PIPELINES_FOR_SPECIFIED_OBJECT_TYPE

阶段名称 → 阶段ID: 从管道阶段响应中提取
负责人名称 → 负责人ID: 使用
```
HUBSPOT_RETRIEVE_OWNERS
```

Pagination

分页处理

Search endpoints use cursor-based pagination
Follow
```
paging.next.after
```
until absent
Typical limit: 100 records per page
Pass
```
after
```
value from previous response to get next page

搜索端点使用基于游标的分页
跟随
```
paging.next.after
```
直到该字段不存在
典型限制：每页100条记录
传递上一次响应中的
```
after
```
值以获取下一页

Batch Operations

批量操作

Most create/update endpoints support batching with max 100 records per call
For larger datasets, chunk into groups of 100
Store returned IDs from each batch before proceeding
Use batch endpoints (
```
CREATE_CONTACTS
```
,
```
CREATE_COMPANIES
```
,
```
UPDATE_COMPANIES
```
) instead of single-record endpoints for efficiency

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

Known Pitfalls

常见注意事项

Property names: All search/filter endpoints use internal property names, NOT display labels. Always call
```
READ_ALL_PROPERTIES_FOR_OBJECT_TYPE
```
to discover correct names
Batch limits: Max 100 records per batch operation. Larger sets must be chunked
Response structure: Search results are nested under
```
response.data.results
```
with properties as string values
Date formats: Date properties may be epoch-ms or ISO strings depending on endpoint. Parse defensively
Immutable names: Property names cannot be changed after creation. Plan naming conventions carefully
Cursor pagination: Use
```
paging.next.after
```
cursor, not page numbers. Continue until
```
after
```
is absent
Duplicate prevention: Always search before creating contacts/companies to avoid duplicates
Auth verification: Run
```
HUBSPOT_GET_ACCOUNT_INFO
```
first; auth failures cascade to all subsequent calls

属性名称: 所有搜索/筛选端点使用内部属性名称，而非显示标签。始终调用
```
READ_ALL_PROPERTIES_FOR_OBJECT_TYPE
```
来获取正确名称
批量限制: 批量操作每批最多100条记录。更大的数据集必须拆分处理
响应结构: 搜索结果嵌套在
```
response.data.results
```
下，属性为字符串值
日期格式: 日期属性可能是毫秒级时间戳或ISO字符串，取决于端点。需灵活解析
不可变名称: 属性名称创建后无法更改。需仔细规划命名规范
游标分页: 使用
```
paging.next.after
```
游标，而非页码。直到
```
after
```
字段不存在为止
重复预防: 创建联系人/公司前务必先搜索，避免重复
认证验证: 先运行
```
HUBSPOT_GET_ACCOUNT_INFO
```
；认证失败会影响后续所有调用

Quick Reference

快速参考

Task	Tool Slug	Key Params
Create contact	`HUBSPOT_CREATE_CONTACT`	`properties: {email, firstname, lastname}`
Batch create contacts	`HUBSPOT_CREATE_CONTACTS`	`inputs: [{properties}]` (max 100)
Search contacts	`HUBSPOT_SEARCH_CONTACTS_BY_CRITERIA`	`filterGroups, properties, limit, after`
Create companies	`HUBSPOT_CREATE_COMPANIES`	`inputs: [{properties}]` (max 100)
Search companies	`HUBSPOT_SEARCH_COMPANIES`	`filterGroups, properties, after`
Search deals	`HUBSPOT_SEARCH_DEALS`	`filterGroups, properties, after`
Get pipelines	`HUBSPOT_RETRIEVE_ALL_PIPELINES_FOR_SPECIFIED_OBJECT_TYPE`	`objectType: 'deals'`
Search tickets	`HUBSPOT_SEARCH_TICKETS`	`filterGroups, properties, after`
List properties	`HUBSPOT_READ_ALL_PROPERTIES_FOR_OBJECT_TYPE`	`objectType`
Create property	`HUBSPOT_CREATE_PROPERTY_FOR_SPECIFIED_OBJECT_TYPE`	`objectType, name, label, type, fieldType`
Get owners	`HUBSPOT_RETRIEVE_OWNERS`	None
Verify connection	`HUBSPOT_GET_ACCOUNT_INFO`	None

任务	工具标识	关键参数
创建联系人	`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`	无

When to Use

适用场景

This skill is applicable to execute the workflow or actions described in the overview.

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