HubSpot MCP（または公式APIラッパ）を整理｜コンタクト検索・チケット作成の任せ方（要公式確認）
目次 クリックで開く
HubSpotを外部のAIツールや自社システムと連携させる際、エンジニアや実務担当者が直面するのが「どの接続方式が最適か」という問題です。特に、Anthropic社が提唱したMCP（Model Context Protocol）の登場により、ClaudeなどのAIエージェントから直接HubSpotのデータを参照・操作することが容易になりました。本記事では、HubSpotの公式APIラッパ（SDK）とMCPの使い分けから、実務で頻出する「コンタクト検索」「チケット作成」の具体的な実装・設定方法までを徹底解説します。
HubSpot MCPと公式APIラッパの全容｜AI時代のCRM連携
現在、HubSpotをプログラムやAIから操作する手法は大きく分けて2つあります。一つは従来からある公式APIラッパ（Client Libraries）を用いる方法、もう一つは最新の標準規格であるMCPを用いる方法です。
MCP（Model Context Protocol）が変えるHubSpot操作
MCPは、AIモデルが外部ツールやデータソースとシームレスに通信するためのオープン標準です。HubSpot MCPサーバを利用すると、開発者が個別にエンドポイントを叩くコードを書かなくても、AI側が「コンタクトを探して」「未解決のチケットをリストアップして」といった指示を理解し、実行できるようになります。これにより、プロンプトベースでのCRM操作が現実的になります。
公式APIラッパ（Client Libraries）を活用すべきケース
一方で、特定の業務フローに組み込まれたバッチ処理や、厳密なエラーハンドリングが必要な自社アプリケーションの開発には、HubSpotが提供する公式SDK（Node.js, Python, PHP, Ruby, Go等）が適しています。
公式ラッパは、リトライロジックや型定義が組み込まれているため、堅牢なシステム構築に向いています。例えば、複雑なデータ移行や、基幹システムとの定期同期などは、MCPよりもAPIラッパで制御すべき領域です。
MCP vs 公式APIラッパ 比較表
用途に応じた選択基準を以下の表にまとめました。
| 比較項目 | HubSpot MCP | 公式APIラッパ（SDK） |
|---|---|---|
| 主な利用者 | AIエージェント、Claude Desktop利用者 | システム開発者、SRE |
| 実装の難易度 | 低い（設定ファイルに記述） | 中〜高い（プログラミングが必要） |
| 柔軟性 | AIの解釈に依存 | 極めて高い（細かな制御が可能） |
| 主な用途 | 対話型のデータ抽出、簡易なタスク実行 | 基幹システム連携、複雑な自動化ワークフロー |
| 認証方式 | 非公開アプリのアクセストークン | 非公開アプリのアクセストークン / OAuth |
CRMのデータをただ参照するだけでなく、他システムと高度に連携させる場合は、全体設計が重要になります。例えば、名刺管理システムから得た情報をHubSpotへ同期し、さらにそれをAIで分析するといった構成については、【プロの名刺管理SaaS本音レビュー】Sansan・Eight Teamの特性と、CRM連携によるデータ基盤構築の実務の記事も参考になるはずです。
実務で必須となる「コンタクト検索」の実装ガイド
CRM連携において最も利用頻度が高いのが「コンタクトの検索」です。単純なID指定の取得とは異なり、条件を指定して対象を絞り込むには「Search API」を正しく扱う必要があります。
Search APIを用いた高度なフィルタリング
HubSpotのSearch API（/crm/v3/objects/contacts/search）では、filterGroupsを用いて複雑な条件を指定できます。例えば、「特定のドメインを持つメールアドレス」かつ「最終更新日が1週間以内」といった抽出が可能です。
公式仕様の重要ポイント：
検索APIでは、一度に取得できる件数に上限（デフォルト100件、最大100件）があります。それ以上のデータを取得する場合は、
pagingパラメータを使用してオフセット指定を行う必要があります。
よくある検索パラメータの設定例
以下は、Node.jsの公式SDKを用いたメールアドレスによる検索のコードイメージです。
const filter = { propertyName: 'email', operator: 'EQ', value: 'example@domain.com' };
const filterGroup = { filters: [filter] };
const publicObjectSearchRequest = {
filterGroups: [filterGroup],
properties: ['firstname', 'lastname', 'company'],
limit: 1,
after: 0,
};
このように、必要なプロパティ（properties）を明示的に指定しないと、デフォルトの項目しか返ってこない点に注意してください。
検索結果のパジネーション処理と注意点
大規模なコンタクトリストを持つテナントの場合、検索結果が数千件に及ぶことがあります。Search APIは大量のデータ一括エクスポート用ではないため、10,000件を超えるようなオフセット指定には制限がかかる場合があります。その場合は、プロパティによるフィルタリング条件を細かく分けるか、Read APIの全件取得を検討してください。これらCRMデータの扱いに関する全体像は、【図解】SFA・CRM・MA・Webの違いを解説。高額ツールに依存しない『データ連携の全体設計図』で詳しく解説しています。
AIに「チケット作成」を任せるためのアーキテクチャ
カスタマーサポートの自動化において、AIエージェントにHubSpotの「チケット」を作成させるワークフローは非常に強力です。MCPを経由することで、ユーザーとの会話内容から適切なチケット件名や優先度をAIが判断し、APIを叩くことができます。
チケットオブジェクトの基本構造と必須プロパティ
チケット作成（POST /crm/v3/objects/tickets）において、最低限必要なのはhs_pipelineとhs_pipeline_stageです。これらはHubSpotの設定画面から内部IDを確認しておく必要があります。
- subject: チケットの件名
- hs_pipeline: パイプラインID（デフォルトは “default”）
- hs_pipeline_stage: ステージID（「新規」や「対応中」などのID）
- hubspot_owner_id: 担当者ID
コンタクトとチケットの関連付け（Associations）の手順
単にチケットを作成しただけでは、どの顧客からの問い合わせか判別できません。チケット作成時のリクエストにassociationsを含めることで、コンタクトとチケットを紐付けた状態で生成できます。
"associations": [
{
"to": { "id": "CONTACT_ID" },
"types": [
{ "associationCategory": "HUBSPOT_DEFINED", "associationTypeId": 16 }
]
}
]
※associationTypeIdはオブジェクトの種類によって異なります。チケットからコンタクトへの紐付けは通常「16」ですが、最新の公式ドキュメントで必ず確認してください。
AIエージェント経由でチケットを自動生成する際のプロンプト設計
MCPを利用する場合、AIに対して「ユーザーが困っている内容を要約し、サポートパイプラインの『新規』ステージにチケットを作成してください。その際、コンタクトID：XXXXと関連付けてください」という明確なインストラクションを与えることで、実務に耐えうる自動化が可能になります。
こうした自動化は、バックオフィスの生産性を劇的に向上させます。もし、HubSpotだけでなく会計システムなども含めた全社的なDXを検討しているなら、Excelと紙の限界を突破する「Google Workspace × AppSheet」業務DX完全ガイドも、ツール連携のヒントとなるはずです。
セキュアな連携のための認証設定ステップ
HubSpot APIを利用する際、かつての「APIキー」は2022年に廃止されました。現在は「非公開アプリ（Private Apps）」による認証が標準です。
非公開アプリ（Private Apps）の作成とトークン管理
- HubSpotの設定 > 統合 > 非公開アプリ を開く。
- [新しい非公開アプリを作成] をクリック。
- 「スコープ（Scopes）」タブで、必要な権限を選択する。
- アプリを保存し、発行されたアクセス（ベアラー）トークンを安全な場所に保管する。
最小権限の原則に基づくスコープ（Scopes）の選び方
セキュリティリスクを最小限に抑えるため、必要以上の権限は付与しないでください。
- コンタクトの検索・参照のみ：
crm.objects.contacts.read - チケットの作成：
crm.objects.tickets.write - 所有者情報の取得：
crm.users.read
セキュリティ上の注意点：環境変数の保護とIP制限
アクセストークンをソースコードに直書きするのは厳禁です。必ず環境変数（.env等）に格納し、GitHubなどのバージョン管理システムに漏洩しないよう.gitignoreを徹底してください。また、より高いセキュリティが求められる環境では、HubSpotのWebhookやAPI利用を特定のIPアドレスからのみ許可するなどの対策（インフラレベルの制限）も検討すべきです。
トラブルシューティング：よくあるエラーと解決策
実装中によく遭遇するエラーとその原因、対策を整理しました。
429 Too Many Requests（レート制限）への対処
HubSpot APIには、プランに応じた「10秒あたりのリクエスト上限」があります。
Free/Starterプランの場合は秒間10リクエスト程度に制限されるため、ループ処理内でAPIを叩く際は、スリープ処理を入れるか、Batch API（複数のオブジェクトを一括処理するエンドポイント）への切り替えが必要です。
403 Forbidden（スコープ不足）の確認箇所
「認証は通っているが操作ができない」場合、ほぼ確実にスコープ設定の不足です。非公開アプリの設定に戻り、対象のオブジェクト（Contacts, Tickets等）のRead/Write権限が正しくチェックされているか確認し、更新してください。更新後、トークンの再発行が必要な場合もあります。
APIレスポンスが期待通りでない場合のデバッグ手法
特にSearch APIで「ヒットするはずのデータが返ってこない」場合、プロパティ名が正しいかを確認してください。HubSpotの内部プロパティ名（Internal Name）は、表示名と異なることが多々あります（例：表示名「会社名」に対し、内部名は company）。設定 > プロパティ から、各項目の「」アイコンをクリックして内部名を確認する癖をつけましょう。
HubSpotのMCP活用やAPI連携は、一度構築すれば業務効率を飛躍的に高めます。自社の要件に合わせて、柔軟なMCPか、堅牢なAPIラッパかを選択し、セキュアなCRM運用を実現してください。
HubSpot連携を成功させるための実務チェックリスト
HubSpotのAPIやMCPを活用した自動化を実装する際、エンジニアが陥りやすい「仕様の壁」がいくつか存在します。開発に着手する前に、以下の3つのポイントを必ずチェックしてください。
1. 内部プロパティ名の確認（表示名との乖離）
前述の通り、HubSpotの画面上で見える名称と、APIで指定する「内部システム名」は異なります。カスタムプロパティを作成した際、日本語の表示名から自動生成された内部名が p12345_... のような形式になっている場合もあります。必ず「設定 ＞ プロパティ」から各項目の内部名を確認し、ソースコードやMCPの設定に反映させてください。
2. プランごとのAPIレート制限（Rate Limits）
APIの実行回数制限は、契約している製品プランによって大きく変動します。特に一括処理やAIによる連続実行を行う場合は、以下の制限を考慮した設計が必要です。
| プラン | 10秒あたりのリクエスト上限 | 1日あたりの上限（24時間） |
|---|---|---|
| Free & Starter | 10件 | 250,000件 |
| Professional & Enterprise | 150件 | 500,000件 |
| APIアドオン（追加オプション） | 200件 | 1,000,000件以上 |
※最新の数値は HubSpot公式：API使用制限ドキュメント を参照してください。
3. テスト環境（サンドボックス）の活用
本番稼働中のCRMデータを誤って書き換えないよう、Enterpriseプラン以上の場合は「標準サンドボックス」を、開発者向けには「アプリテストアカウント」を使用することを強く推奨します。
公式リソースとさらなるデータ活用のために
HubSpotを単体で使うだけでなく、他のSaaSや社内データ基盤と統合することで、その真価を発揮します。より高度なアーキテクチャ設計については、以下のリソースも参考にしてください。
- HubSpot API 開発者ドキュメント（公式）：すべてのエンドポイントの詳細仕様が網羅されています。
- 【図解】SFA・CRM・MA・Webの違いを解説。高額ツールに依存しない『データ連携の全体設計図』：HubSpotをエコシステムの中央に据える際の全体像を解説しています。
- 高額なCDPは不要？BigQuery・dbt・リバースETLで構築する「モダンデータスタック」：CRMデータをDWHへ集約し、さらに高度な分析や配信へ繋げるためのガイドです。
HubSpotのMCP対応は、AIによる業務自動化の第一歩に過ぎません。APIラッパによる堅牢な実装と、MCPによる柔軟なAI操作を組み合わせることで、顧客対応の質とスピードを両立させた次世代のCRM運用を実現しましょう。
ご相談・お問い合わせ
本記事の内容を自社の状況に当てはめたい場合や、導入・運用の設計を一緒に整理したい場合は、当社までお気軽にご相談ください。担当より折り返しご連絡いたします。