Hubspot Automation

1---
2name: hubspot-automation
3description: "Automate HubSpot CRM operations (contacts, companies, deals, tickets, properties) via Rube MCP using Composio integration."
4requires:
5  mcp: [rube]
6---
7 
8# HubSpot CRM Automation via Rube MCP
9 
10Automate HubSpot CRM workflows including contact/company management, deal pipeline tracking, ticket search, and custom property creation through Composio's HubSpot toolkit.
11 
12## Prerequisites
13 
14- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
15- Active HubSpot connection via `RUBE_MANAGE_CONNECTIONS` with toolkit `hubspot`
16- Always call `RUBE_SEARCH_TOOLS` first to get current tool schemas
17 
18## Setup
19 
20**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.
21 
22 
231. Verify Rube MCP is available by confirming `RUBE_SEARCH_TOOLS` responds
242. Call `RUBE_MANAGE_CONNECTIONS` with toolkit `hubspot`
253. If connection is not ACTIVE, follow the returned auth link to complete HubSpot OAuth
264. Confirm connection status shows ACTIVE before running any workflows
27 
28## Core Workflows
29 
30### 1. Create and Manage Contacts
31 
32**When to use**: User wants to create new contacts or update existing ones in HubSpot CRM
33 
34**Tool sequence**:
351. `HUBSPOT_GET_ACCOUNT_INFO` - Verify connection and permissions (Prerequisite)
362. `HUBSPOT_SEARCH_CONTACTS_BY_CRITERIA` - Search for existing contacts to avoid duplicates (Prerequisite)
373. `HUBSPOT_READ_A_CRM_PROPERTY_BY_NAME` - Check property metadata for constrained values (Optional)
384. `HUBSPOT_CREATE_CONTACT` - Create a single contact (Required)
395. `HUBSPOT_CREATE_CONTACTS` - Batch create contacts up to 100 (Alternative)
40 
41**Key parameters**:
42- `HUBSPOT_CREATE_CONTACT`: `properties` object with `email`, `firstname`, `lastname`, `phone`, `company`
43- `HUBSPOT_CREATE_CONTACTS`: `inputs` array of `{properties}` objects, max 100 per batch
44- `HUBSPOT_SEARCH_CONTACTS_BY_CRITERIA`: `filterGroups` array with `{filters: [{propertyName, operator, value}]}`, `properties` array of fields to return
45 
46**Pitfalls**:
47- Max 100 records per batch; chunk larger imports
48- 400 'Property values were not valid' if using incorrect property names or enum values
49- Always search before creating to avoid duplicates
50- Auth errors from GET_ACCOUNT_INFO mean all subsequent calls will fail
51 
52### 2. Manage Companies
53 
54**When to use**: User wants to create, search, or update company records
55 
56**Tool sequence**:
571. `HUBSPOT_SEARCH_COMPANIES` - Search existing companies (Prerequisite)
582. `HUBSPOT_CREATE_COMPANIES` - Batch create companies, max 100 (Required)
593. `HUBSPOT_UPDATE_COMPANIES` - Batch update existing companies (Alternative)
604. `HUBSPOT_GET_COMPANY` - Get single company details (Optional)
615. `HUBSPOT_BATCH_READ_COMPANIES_BY_PROPERTIES` - Bulk read companies by property values (Optional)
62 
63**Key parameters**:
64- `HUBSPOT_CREATE_COMPANIES`: `inputs` array of `{properties}` objects, max 100
65- `HUBSPOT_SEARCH_COMPANIES`: `filterGroups`, `properties`, `sorts`, `limit`, `after` (pagination cursor)
66 
67**Pitfalls**:
68- Max 100 per batch; chunk larger sets
69- Store returned IDs immediately for downstream operations
70- Property values must match exact internal names, not display labels
71 
72### 3. Manage Deals and Pipeline
73 
74**When to use**: User wants to search deals, view pipeline stages, or track deal progress
75 
76**Tool sequence**:
771. `HUBSPOT_RETRIEVE_ALL_PIPELINES_FOR_SPECIFIED_OBJECT_TYPE` - Map pipeline and stage IDs/names (Prerequisite)
782. `HUBSPOT_SEARCH_DEALS` - Search deals with filters (Required)
793. `HUBSPOT_RETRIEVE_PIPELINE_STAGES` - Get stage details for one pipeline (Optional)
804. `HUBSPOT_RETRIEVE_OWNERS` - Get owner/rep details (Optional)
815. `HUBSPOT_GET_DEAL` - Get single deal details (Optional)
826. `HUBSPOT_LIST_DEALS` - List all deals without filters (Fallback)
83 
84**Key parameters**:
85- `HUBSPOT_SEARCH_DEALS`: `filterGroups` with filters on `pipeline`, `dealstage`, `createdate`, `closedate`, `hubspot_owner_id`; `properties`, `sorts`, `limit`, `after`
86- `HUBSPOT_RETRIEVE_ALL_PIPELINES_FOR_SPECIFIED_OBJECT_TYPE`: `objectType` set to `'deals'`
87 
88**Pitfalls**:
89- Results nested under `response.data.results`; properties are often strings (amounts, dates)
90- Stage IDs may be readable strings or opaque numeric IDs; use `label` field for display
91- Filters must use internal property names (`pipeline`, `dealstage`, `createdate`), not display names
92- Paginate via `paging.next.after` until absent
93 
94### 4. Search and Filter Tickets
95 
96**When to use**: User wants to find support tickets by status, date, or criteria
97 
98**Tool sequence**:
991. `HUBSPOT_SEARCH_TICKETS` - Search with filterGroups (Required)
1002. `HUBSPOT_READ_ALL_PROPERTIES_FOR_OBJECT_TYPE` - Discover available property names (Fallback)
1013. `HUBSPOT_GET_TICKET` - Get single ticket details (Optional)
1024. `HUBSPOT_GET_TICKETS` - Bulk fetch tickets by IDs (Optional)
103 
104**Key parameters**:
105- `HUBSPOT_SEARCH_TICKETS`: `filterGroups`, `properties` (only listed fields are returned), `sorts`, `limit`, `after`
106 
107**Pitfalls**:
108- Incorrect `propertyName`/`operator` returns zero results without errors
109- Date filtering may require epoch-ms bounds; mixing formats causes mismatches
110- Only fields in the `properties` array are returned; missing ones break downstream logic
111- Use READ_ALL_PROPERTIES to discover exact internal property names
112 
113### 5. Create and Manage Custom Properties
114 
115**When to use**: User wants to add custom fields to CRM objects
116 
117**Tool sequence**:
1181. `HUBSPOT_READ_ALL_PROPERTIES_FOR_OBJECT_TYPE` - List existing properties (Prerequisite)
1192. `HUBSPOT_READ_PROPERTY_GROUPS_FOR_OBJECT_TYPE` - List property groups (Optional)
1203. `HUBSPOT_CREATE_PROPERTY_FOR_SPECIFIED_OBJECT_TYPE` - Create a single property (Required)
1214. `HUBSPOT_CREATE_BATCH_OF_PROPERTIES` - Batch create properties (Alternative)
1225. `HUBSPOT_UPDATE_SPECIFIC_CRM_PROPERTY` - Update existing property definition (Optional)
123 
124**Key parameters**:
125- `HUBSPOT_CREATE_PROPERTY_FOR_SPECIFIED_OBJECT_TYPE`: `objectType`, `name`, `label`, `type` (string/number/date/enumeration), `fieldType`, `groupName`, `options` (for enumerations)
126 
127**Pitfalls**:
128- Property names are immutable after creation; choose carefully
129- Enumeration options must be pre-defined with `value` and `label`
130- Group must exist before assigning properties to it
131 
132## Common Patterns
133 
134### ID Resolution
135- **Property display name → internal name**: Use `HUBSPOT_READ_ALL_PROPERTIES_FOR_OBJECT_TYPE`
136- **Pipeline name → pipeline ID**: Use `HUBSPOT_RETRIEVE_ALL_PIPELINES_FOR_SPECIFIED_OBJECT_TYPE`
137- **Stage name → stage ID**: Extract from pipeline stages response
138- **Owner name → owner ID**: Use `HUBSPOT_RETRIEVE_OWNERS`
139 
140### Pagination
141- Search endpoints use cursor-based pagination
142- Follow `paging.next.after` until absent
143- Typical limit: 100 records per page
144- Pass `after` value from previous response to get next page
145 
146### Batch Operations
147- Most create/update endpoints support batching with max 100 records per call
148- For larger datasets, chunk into groups of 100
149- Store returned IDs from each batch before proceeding
150- Use batch endpoints (`CREATE_CONTACTS`, `CREATE_COMPANIES`, `UPDATE_COMPANIES`) instead of single-record endpoints for efficiency
151 
152## Known Pitfalls
153 
154- **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
155- **Batch limits**: Max 100 records per batch operation. Larger sets must be chunked
156- **Response structure**: Search results are nested under `response.data.results` with properties as string values
157- **Date formats**: Date properties may be epoch-ms or ISO strings depending on endpoint. Parse defensively
158- **Immutable names**: Property names cannot be changed after creation. Plan naming conventions carefully
159- **Cursor pagination**: Use `paging.next.after` cursor, not page numbers. Continue until `after` is absent
160- **Duplicate prevention**: Always search before creating contacts/companies to avoid duplicates
161- **Auth verification**: Run `HUBSPOT_GET_ACCOUNT_INFO` first; auth failures cascade to all subsequent calls
162 
163## Quick Reference
164 
165| Task | Tool Slug | Key Params |
166|------|-----------|------------|
167| Create contact | `HUBSPOT_CREATE_CONTACT` | `properties: {email, firstname, lastname}` |
168| Batch create contacts | `HUBSPOT_CREATE_CONTACTS` | `inputs: [{properties}]` (max 100) |
169| Search contacts | `HUBSPOT_SEARCH_CONTACTS_BY_CRITERIA` | `filterGroups, properties, limit, after` |
170| Create companies | `HUBSPOT_CREATE_COMPANIES` | `inputs: [{properties}]` (max 100) |
171| Search companies | `HUBSPOT_SEARCH_COMPANIES` | `filterGroups, properties, after` |
172| Search deals | `HUBSPOT_SEARCH_DEALS` | `filterGroups, properties, after` |
173| Get pipelines | `HUBSPOT_RETRIEVE_ALL_PIPELINES_FOR_SPECIFIED_OBJECT_TYPE` | `objectType: 'deals'` |
174| Search tickets | `HUBSPOT_SEARCH_TICKETS` | `filterGroups, properties, after` |
175| List properties | `HUBSPOT_READ_ALL_PROPERTIES_FOR_OBJECT_TYPE` | `objectType` |
176| Create property | `HUBSPOT_CREATE_PROPERTY_FOR_SPECIFIED_OBJECT_TYPE` | `objectType, name, label, type, fieldType` |
177| Get owners | `HUBSPOT_RETRIEVE_OWNERS` | None |
178| Verify connection | `HUBSPOT_GET_ACCOUNT_INFO` | None |