hubspot-automation

Rube MCP による HubSpot CRM の自動化

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

前提条件

• Rube MCP が接続されている必要があります（RUBE_SEARCH_TOOLS を利用可能）
• RUBE_MANAGE_CONNECTIONS で toolkit hubspot を指定して、有効な HubSpot 接続を確立してください
• 現在のツールスキーマを取得するため、必ず最初に RUBE_SEARCH_TOOLS を呼び出してください

セットアップ

Rube MCP の取得：クライアント設定で https://rube.app/mcp を MCP サーバーとして追加します。対象の HubSpot アカウントでは、返された認証フローを完了し、必要なスコープを許可する必要があります。

1. RUBE_SEARCH_TOOLS が応答することを確認し、Rube MCP が利用可能であることを確認します
2. toolkit hubspot を指定して RUBE_MANAGE_CONNECTIONS を呼び出します
3. 接続が ACTIVE でない場合は、返された認証リンクに従って HubSpot OAuth を完了します
4. ワークフローを実行する前に、接続ステータスが ACTIVE になっていることを確認します

アカウント、スキーマ、書き込み権限の範囲

これらの過去のスラッグやパラメーターの例を使う前に、正確なアカウントを特定し、現在のスキーマを確認してください。作成前に検索すれば重複を減らせますが、並行処理に対する一意性は保証されません。サポートされている一意の ID やアップサートのセマンティクスを使用し、書き込み結果が不確かな場合は、再試行する前に状態を照合してください。返されるコンタクトフィールドを制限し、ログから個人データを削除し、バッチのサイズと対象を事前に確認して、部分的な失敗の結果を保持してください。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。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 を呼び出してください
• バッチ制限: 1 回のバッチ操作につき最大 100 レコードです。それより大きいセットは分割する必要があります
• レスポンス構造: 検索結果は response.data.results の下にネストされ、プロパティは文字列値として格納されます
• 日付形式: 日付プロパティは、エンドポイントによって epoch-ms または 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 統合を使用して、Rube MCP 経由で HubSpot CRM の操作 (連絡先、企業、取引、チケット、プロパティ) を自動化します。

制限事項

• このスキルは、タスクが上記の範囲に明確に一致する場合にのみ使用してください。
• 出力を、環境固有の検証、テスト、または専門家によるレビューの代替として扱わないでください。
• 必要な入力、権限、安全境界、または成功基準が欠けている場合は、停止して確認を求めてください。