hubspot-automation

Rube MCP による HubSpot CRM の自動化

Composio の HubSpot ツールキットを通じて、コンタクトや会社の管理、取引パイプラインの追跡、チケットの検索、カスタムプロパティの作成など、HubSpot CRM のワークフローを自動化します。

ツールキットのドキュメント: composio.dev/toolkits/hubspot

前提条件

• Rube MCP が接続されていること（RUBE_SEARCH_TOOLS が利用可能）
• RUBE_MANAGE_CONNECTIONS を通じて hubspot ツールキットへの 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 - 1 件のコンタクトを作成します（必須）
5. HUBSPOT_CREATE_CONTACTS - 最大 100 件のコンタクトを一括作成します（代替手段）

主なパラメーター:

• HUBSPOT_CREATE_CONTACT: email、firstname、lastname、phone、company を含む properties オブジェクト
• HUBSPOT_CREATE_CONTACTS: {properties} オブジェクトの inputs 配列。1 回のバッチにつき最大 100 件
• HUBSPOT_SEARCH_CONTACTS_BY_CRITERIA: {filters: [{propertyName, operator, value}]} を含む filterGroups 配列、返すフィールドの properties 配列

注意点:

• 1 回のバッチにつき最大 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 - 1 件の会社の詳細を取得します（任意）
5. HUBSPOT_BATCH_READ_COMPANIES_BY_PROPERTIES - プロパティ値を指定して会社を一括読み込みします（任意）

主なパラメーター:

• HUBSPOT_CREATE_COMPANIES: {properties} オブジェクトの inputs 配列。最大 100 件
• HUBSPOT_SEARCH_COMPANIES: filterGroups、properties、sorts、limit、after（ページネーションカーソル）

注意点:

• 1 回のバッチにつき最大 100 件です。件数の多いセットは分割してください
• 後続の操作に備えて、返された ID をすぐに保存してください
• プロパティ値には表示ラベルではなく、正確な内部名を指定する必要があります

3. 取引とパイプラインを管理する

使用する場面：取引を検索したり、パイプラインのステージを確認したり、取引の進捗を追跡したい場合

ツールの順序：

1. HUBSPOT_RETRIEVE_ALL_PIPELINES_FOR_SPECIFIED_OBJECT_TYPE - パイプラインとステージの ID／名前を対応付けます（前提条件）
2. HUBSPOT_SEARCH_DEALS - フィルターを使って取引を検索します（必須）
3. HUBSPOT_RETRIEVE_PIPELINE_STAGES - 1 つのパイプラインのステージ詳細を取得します（任意）
4. HUBSPOT_RETRIEVE_OWNERS - オーナー／担当者の詳細を取得します（任意）
5. HUBSPOT_GET_DEAL - 1 件の取引の詳細を取得します（任意）
6. HUBSPOT_LIST_DEALS - フィルターを使わずにすべての取引を一覧表示します（代替手段）

主なパラメーター：

• HUBSPOT_SEARCH_DEALS：pipeline、dealstage、createdate、closedate、hubspot_owner_id のフィルターを含む filterGroups、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 - 1 件のチケットの詳細を取得します（任意）
4. HUBSPOT_GET_TICKETS - ID を指定して複数のチケットを一括取得します（任意）

主なパラメーター：

• HUBSPOT_SEARCH_TICKETS：filterGroups、properties（一覧に含まれるフィールドのみが返されます）、sorts、limit、after

注意点：

• propertyName／operator が正しくない場合、エラーなしで結果が 0 件になります。
• 日付の絞り込みにはエポックミリ秒の範囲が必要な場合があります。形式を混在させると不一致が発生します。
• 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 - 1 つのプロパティを作成します（必須）
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（enumeration 用）

注意点：

• プロパティ名は作成後に変更できません。慎重に選んでください。
• enumeration の選択肢は、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 がなくなるまで続けてください。
• 一般的な上限は 1 ページあたり 100 件です。
• 次のページを取得するには、前のレスポンスの after 値を渡してください。

一括操作

• ほとんどの作成／更新エンドポイントは、1 回の呼び出しにつき最大 100 件の一括処理に対応しています。
• さらに大きなデータセットの場合は、100 件ずつのグループに分割してください。
• 次に進む前に、各バッチから返された ID を保存してください。
• 効率化のため、単一レコード用エンドポイントではなく、一括処理用エンドポイント（CREATE_CONTACTS、CREATE_COMPANIES、UPDATE_COMPANIES）を使用してください。

既知の注意点

• プロパティ名：すべての検索／フィルターエンドポイントでは、表示ラベルではなく内部プロパティ名を使用します。正しい名前を確認するには、必ず READ_ALL_PROPERTIES_FOR_OBJECT_TYPE を呼び出してください
• バッチの上限：各バッチ操作の上限は100レコードです。それを超える場合は、分割する必要があります
• レスポンスの構造：検索結果は response.data.results に格納され、プロパティは文字列値として返されます
• 日付の形式：日付プロパティは、エンドポイントによってエポックミリ秒またはISO文字列の場合があります。どちらにも対応できるように解析してください
• 変更できない名前：プロパティ名は作成後に変更できません。命名規則は慎重に計画してください
• カーソルページネーション：ページ番号ではなく、paging.next.after カーソルを使用します。after がなくなるまで続行してください
• 重複の防止：重複を避けるため、コンタクトや会社を作成する前に必ず検索してください
• 認証の確認：最初に HUBSPOT_GET_ACCOUNT_INFO を実行してください。認証エラーが発生すると、その後のすべての呼び出しに影響します

クイックリファレンス

タスク	ツールスラッグ	主なパラメーター
コンタクトを作成	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