HubSpot

ohneben の HubSpot MCP

---

ライセンスとチェック

MCP レジストリ

これまでで最も充実した HubSpot MCP サーバーです。 Claude、 Cursor、その他の MCP クライアントから、 HubSpot アカウント全体を自然な言葉で操作できます。

この Model Context Protocol サーバーは、 HubSpot の公開 API 全体、102 の API にまたがる 1,076 のエンドポイントを 687 個のツールとして公開します。CRM、CMS、マーケティング、自動化、 会話、コマース、ファイル、設定、Webhook などを、HubSpot 独自の OpenAPI 定義から直接生成しています。HubSpot がオブジェクトの種類ごとに繰り返し提供する エンドポイントは、それぞれ 1 つのツールにまとめられています （検索ツールを 32 個別々に用意する代わりに、objectType: "deals" を指定する crm_objects_search）。また、すべてのツールの説明に使用するタイミングが 記載されています。すべてのツールは安全性に応じて分類され（🟢 読み取り専用／ 🟡 書き込み／🔴 破壊的）、さらにこのサーバー独自の機能として、Hub とプランを 認識します。HubSpot は各 API に必要な Hub とプラン（Free／Starter／Professional／ Enterprise）を公開しており、このサーバーはその情報を各ツールに反映するほか、 お使いの ポータルのライブ機能レポートも提供します。stdio（Claude Desktop などのローカルランチャー向け）または Streamable HTTP（Docker で ホストする場合）で動作し、リトライ、HubSpot のバースト上限に合わせて調整した クライアント側レート制限、リクエストタイムアウトを備えているため、実際の アカウントでも安定して動作します。

これを選ぶ理由

MCP サーバーの中には、API の一部をそのまま転送するだけのものもあります。 このサーバーは、LLM に安心して任せられること、網羅性、 実際の運用が簡単であることを目指して構築されています。

得られるもの	重要な理由
全1,076エンドポイント — 公開APIのすべて	連絡先、会社、取引、チケット、あらゆるエンゲージメントの種類、関連付けv4、プロパティ、パイプライン、リスト、インポート／エクスポート、マーケティングメールとイベント、キャンペーン、フォーム、トランザクションメール、シーケンス、ワークフロー／アクション、会話とカスタムチャネル、CMSのページ／投稿／HubDB／ソースコード、ファイル、コマース（請求書、注文、カート、支払い、サブスクリプション）、設定、Webhook――厳選して一部だけにしたり、取りこぼしたりすることはありません。ほとんどのサーバーが提供するCRMツールは約30個にとどまります。
似たツールを水増しせず、687個のツールを提供	HubSpotでは、32種類のCRMオブジェクト、ランディングページとサイトページ、ブログ投稿・著者・タグについて、同じエンドポイントが繰り返し登場します。これらはセレクター引数（objectType、pageType、blogResource）を使うそれぞれ1つのツールにまとめられているため、crm_objects_searchで連絡先、取引、チケット、カスタムオブジェクトを検索できます。各呼び出しは、これまでとまったく同じエンドポイントに送信され、そのエンドポイントのスコープとプラン要件のヒントも適用されます。
ツールを使うべきタイミングがわかる説明	各説明では、まずツールの機能を説明し、次に同系列の別ツールを優先すべき状況（crm_objects_listでは、フィルタリングにcrm_objects_search、IDがわかっている場合にcrm_objects_batch_readを案内）、変更内容、プランとスコープ、呼び出すエンドポイントを説明します。ドキュメントに記載されていないHubSpotのパラメーターにも説明が付きます。
Hubとプランの要件を把握 (これに対応しているのはほかにありません)	HubSpotのAPIはHubとプラン階層によって利用が制限されます。HubDBにはContent／Marketing HubのProfessional、カスタムオブジェクトのスキーマにはEnterprise、シーケンスにはSales／ServiceのProfessionalが必要です。すべてのツールに、HubSpot公式のAPIインデックスに基づく要件が記載されています。
起動時にアクセスを確認	サーバーの起動時にトークンのスコープを読み取り、有料プランまたはベータ版のAPIグループをすべて、低コストの読み取りリクエストで確認します。モデルには結果がサーバーの指示として渡され、検索結果には各ツールをこのトークンで使えるかどうかが表示されます。また、hubspot_get_capabilitiesでは、追加すべきスコープとともに各ステータスを確認できます。原因不明の403エラーに悩まされることはもうありません。
厳選された安全性カテゴリ 🟢／🟡／🔴	単純に「GET＝安全」とは判定しません。POST …/searchは読み取り専用のクエリ、mergeは取り消し不可、gdpr-deleteは（アーカイブからごみ箱に移動するのとは異なり）完全削除、リストメンバーシップの呼び出しは取り消し可能なリンク操作、POST /crm/v3/importsは一括インポート、トランザクションメールはメッセージを送信する操作として分類されます。
機械可読なMCPアノテーション（readOnlyHint、destructiveHint）	Claudeを含む、アノテーションに対応したホストは読み取りを自動的に信頼し、破壊的な操作の前に確認を求められます。
実行に役立つエラーのヒント	MISSING_SCOPESを伴う403では追加すべき正確なスコープとその設定場所を、アクセス制限のあるAPIで発生した通常の403では必要なプラン階層を、401ではトークンの種類と有効期限に関する案内を、429では制限内容を示します。モデルには何が壊れたかだけでなく、どう直せばよいかも伝わります。
読み取り専用モードとグループによる絞り込み	読み取り専用の🟢ツール302個だけを公開する（HUBSPOT_READ_ONLY=true）か、使用するグループだけに絞り込めます（HUBSPOT_INCLUDE_GROUPS=contacts,deals,cms:*）。エリアのワイルドカードにも対応しています。
デフォルトで検出モード	初期状態では、モデルには6つのツール（約2kトークン）が表示されます。これらを使って687個すべてのエンドポイントツールを検索、確認、実行できるほか、機能確認、GraphQL、未加工リクエスト用のツールも利用できます。HUBSPOT_TOOL_MODE=allを設定すると、すべてのエンドポイントツールが直接公開されます。どちらのモードでも読み取り専用設定が適用されます。
実際のファイルアップロード	マルチパートのエンドポイント（Files、CRMインポート、HubDBインポート、CMSソースコード）が実際に動作します。ファイルの内容はインラインまたはbase64で渡せます。生成されたサーバーのほとんどは、マルチパートにまったく対応できません。
バックオフ付きの自動再試行	一時的な429／5xxレスポンスをジッター付きの指数バックオフで再試行し、HubSpotのRetry-Afterヘッダーに従います。
組み込みレート制限	HubSpotのバースト上限（デフォルトで100 req／10 s）を下回るように自動でスロットリングし、/searchエンドポイント（上限は約5 req/s）には専用の制限を適用します。ツールを一度に多数呼び出しても、429エラーは発生しません。
レスポンスサイズの上限設定	必要に応じて大きなリストレスポンスに上限を設定できます（HUBSPOT_MAX_RESPONSE_CHARS）。1回の呼び出しでモデルのコンテキストウィンドウがいっぱいになるのを防ぎます。
CRM GraphQLのパススルー	HubSpotのGraphQLエンドポイントはクエリ専用なので、ここでは🟢ツールとして扱われます。1回の往復で、連絡先、その会社、その会社の取引を取得できます。
未加工リクエストのための緊急手段	hubspot_api_requestを使えば、HubSpotが新しいエンドポイントやベータ版エンドポイントを公開したその時点からアクセスできます。認証、スロットリング、再試行は引き続きサーバー側で処理されます。
2種類のトランスポート：stdioとStreamable HTTP	Claude Desktopでローカルに使うことも、常時稼働するサーバーを立ち上げ、任意の数のMCPクライアントからHTTP経由で接続することもできます。
Dockerとdocker-compose、ヘルスチェック、自動再起動	本番環境向けのデプロイをすぐに始められます。docker compose upを実行すれば、そのまま稼働し続けます。
HTTPエンドポイントのオプションのベアラートークン認証	localhostの外部からアクセス可能になった時点で、共有シークレットを使ってサーバーを保護できます。
トークンがモデルに渡ることはありません	アクセストークンはサーバーの環境内に保存され、すべてのリクエストに注入されます。アシスタントに見えるのは、ツールの入力とAPIレスポンスだけです。
仕様をそのまま更新	npm run fetch-specsを実行すると、HubSpotの公開インデックスから最新のOpenAPI定義（Hubとプラン階層のメタデータを含む）を取得します。再ビルドするだけで新しいエンドポイントが新しいツールになり、コードを変更する必要はありません。

比較

現在、AI アシスタントから HubSpot にアクセスする方法はいくつかあります。このサーバーを代替手段と比較すると、次のようになります。

	このサーバー	HubSpot 公式 MCP	shinzo-labs hubspot-mcp	mcp-hubspot (buryhuang)	CData MCP
ツール数の目安	約690（全1,076エンドポイント）	約7（厳選、リモート）	100以上	約7	3（汎用 SQL）
公開 API 全体（CRM および CMS・マーケティング・自動化・コマース・ファイル・設定・Webhook）	✅	➖ CRM と一部のコンテンツ読み取り	➖ CRM 中心	❌	❌
ツールごとの Hub とプラン階層の認識	✅	❌	❌	❌	❌
アカウント機能レポート（スコープ・使用状況・利用可能な機能）	✅	❌	❌	❌	❌
読み取り と 書き込み	✅	✅	✅	➖ 一部対応	❌ 読み取り専用
厳選された 🟢 / 🟡 / 🔴 安全カテゴリ	✅	➖	➖	➖	該当なし
readOnlyHint / destructiveHint 注釈	✅	➖	➖	➖	➖
読み取り専用モードとグループフィルタリング	✅	❌	❌	❌	常に読み取り専用
ファイルのアップロード（マルチパート）	✅	❌	❌	❌	❌
GraphQL パススルー	✅	❌	❌	❌	❌
レート制限と自動再試行（429/5xx）	✅	➖	➖	❌	❌
stdio トランスポート	✅	✅ ローカルパッケージ	✅	✅	✅
Streamable-HTTP トランスポート	✅	✅ ホスト型リモート	✅	❌	❌
Docker + compose + ヘルスチェック	✅	❌	➖ Dockerfile	➖ イメージのみ	❌
独自のインフラでセルフホスト	✅	➖ ベンダーのクラウド	✅	✅	✅
言語	TypeScript	TypeScript	TypeScript	Python	Java
ライセンス	MIT	—	MIT	MIT	MIT

_{✅ = 対応 · ➖ = 一部対応 / ドキュメントに記載なし · ❌ = 非対応。各プロジェクトの公開ドキュメントをもとにまとめています。これは非公式プロジェクトであり、HubSpot や記載されているプロジェクトとは提携していません。ツール数は概算で、API の進化に伴い変動します。}

要約： 公式リモートサーバーは、管理された環境を手軽に利用し始めるには最適ですが、厳選された少数のツールしか対象としていません。コミュニティのサーバーは堅実ですが、CRM 中心で、プラン認識や安全対策がありません。このサーバーなら、公開 API 全体、他にはない Hub／プラン認識、両方のトランスポート、本番環境向けの Docker デプロイ、厳選された安全カテゴリを利用できます。セルフホスト型で、トークンは自分で管理でき、ライセンスは MIT です。

できること

接続したら、アシスタントに次のようなことを頼めます。

• 「[email protected] を検索して、会社、進行中の商談、最後にやり取りしたメールを表示して。」
• 「Sales パイプラインに、金額 $12,000 の『Acme expansion』という商談を作成して。ステージは Qualified、関連付け先は Acme Corp. にして。」
• 「今月作成されたライフサイクルステージが MQL のコンタクトを検索して、『Q3 nurture』リストに追加して。」
• 「どの HubDB テーブルがある？『pricing』に行を追加して、テーブルを公開して。」
• 「先月のニュースレターを下書きとして複製して。公開はしないで。」
• 「この CSV をアップロードして、メールアドレスと名を対応付けてコンタクトのインポートを開始して。」
• 「自分のトークンでは何ができる？API の使用状況と、HubDB に必要なスコープのうち不足しているものを確認して。」(→ hubspot_get_capabilities)
• 「重複しているこの2件のコンタクトを統合して。まず両方のレコードを見せて。」

ツールは HubSpot の仕様から自動生成され、🟢 読み取り専用、🟡 書き込み、🔴 破壊的操作に分類されます。そのため、適切に動作するホストは各グループを異なる方法で扱えます。

仕組み

Claude / Cursor / any MCP client  ──MCP──►  this server  ──HTTPS──►  api.hubapi.com (your portal)

サーバーは、同梱された104個の OpenAPI 定義（HubSpot の公開 API インデックスから取得したもので、API ごとのHub／階層の要件も公開されています）を MCP ツールに変換します。変換時には、$ref を解決し、再帰スキーマを保護し、オブジェクト型だけが異なるエンドポイントを1つのツールにまとめ、crm_objects_search や hubdb_tables_create_table のような明確な名前を導出します。また、各ツールに厳選された安全カテゴリ、必要なプラン、OAuth スコープを付与します。アクセス トークンはリクエストごとにサーバー側で挿入されるため、モデルがトークンを見たり扱ったりすることはありません。

Hub とプランの認識

HubSpot は単一の API ではありません。呼び出せる内容は、ポータルが契約しているHub（Marketing、 Sales、Service、Content、Commerce、Operations）とプラン（Free、 Starter、Professional、Enterprise）、およびトークンに付与されたスコープによって異なります。このサーバーは、その実情を踏まえて設計されています。

1. すべてのツールの説明に、HubSpot 独自のインデックスに基づく要件が記載されています。

   🟢 READ-ONLY · Get all published tables.
   Use to page through tables: pass limit, then the after cursor from paging.next.after for the next page.
   …
   Plan: Professional tier of Marketing Hub / Content Hub. Scopes: hubdb.
   Endpoint: GET /cms/v3/hubdb/tables (Hubdb API, CMS)
   

   統合ツールでは、crm_objects_list が objectType パラメーターで、有料プランが必要なオブジェクトタイプを列挙するなど、値ごとに要件を示します。

2. サーバーの起動時にアクセスチェックが実行されます。 HubSpot にはポータルのサブスクリプションを返す API がないため、サーバーは確認可能な情報を組み合わせます。つまり、トークンに付与されたスコープと、有料プランまたはベータ版のグループごとに行う低コストの読み取りです（API 呼び出しは最大約 30 回です。プランによる制限は 403 としてのみ表れます）。 各グループには available、missing_scopes、blocked（プラン、ユーザー権限、またはこの種類のトークンを受け付けない API からの 401）、unverified のいずれかのステータスが設定されます。HubSpot のエラー詳細も判定に使われます。トークンに不足しているスコープを示す 403 はスコープ不足として扱います。一方、対象オブジェクトのスコープをトークンがすでに持っている場合に返される MISSING_SCOPES は、HubSpot がプラン制限に対して返す応答なので、blocked として報告されます。読み取りに成功しても、証明されるのは読み取りアクセスのみです。有料プランが必要な API では書き込みが拒否される場合があり、その旨もレポートに示されます。モデルにはサーバーの指示を通じて概要が提供され、hubspot_search_endpoints は各結果に印を付け（usable_only: true を指定可能）、hubspot_get_capabilities は理由、"unlockedByScopes": "13/16" の件数、追加すべきスコープを含む完全なレポートを返します。refresh: true を指定すると再チェックします。HUBSPOT_CAPABILITY_CHECK=false を設定すると無効になります。

3. 403 には解決方法が含まれます。 スコープ不足の場合は、不足している正確なスコープ名と付与場所が示されます。プランによる制限の場合は、HubSpot が必要とするプランが示されます。

要件

• HubSpot アカウントとサービスキー（または既存のレガシー非公開アプリトークン）。API 認証情報の取得を参照してください。
• 以下のクイックスタートには Docker（macOS／Windows では Docker Desktop）が必要です。または、Node.js ≥ 18 を使ってソースから実行できます。

クイックスタート（Docker）

1. 認証情報を追加します。 設定例をコピーして、値を入力します。

cp .env.example .env
# edit .env → set HUBSPOT_ACCESS_TOKEN
#           → set MCP_AUTH_TOKEN. REQUIRED unless HOST is a loopback address,
#             otherwise the server refuses to start: MCP_AUTH_TOKEN=$(openssl rand -hex 32)

2. サーバーを起動します。

docker compose up -d --build

同梱の docker-compose.yml は 127.0.0.1:8765 のみにバインドするため、サーバーには自分のマシンからアクセスできますが、ネットワークからはアクセスできません。

3. 起動を確認します。

curl -s http://localhost:8765/health
# → {"status":"ok","server":"hubspot-mcp"}

4. MCP クライアントを接続します。 MCP エンドポイントは http://localhost:8765/mcp です。

• Claude Desktop — URL を指定するカスタムコネクター（Settings → Connectors）を追加するか、mcp-remote を使ってローカルでブリッジします。設定の mcpServers に以下を追加してから、アプリを完全に終了し、再起動します。

  {
    "mcpServers": {
      "hubspot": {
        "command": "npx",
        "args": [
          "mcp-remote",
          "http://localhost:8765/mcp",
          "--header", "Authorization: Bearer YOUR_MCP_AUTH_TOKEN"
        ]
      }
    }
  }
  

  （サーバーをトークンなしで実行する場合に限り、--header の行を削除できます。トークンなしでの実行が許可されるのは、ループバックのみにバインドしている場合です。）

• Claude Code — 次のコマンドを実行します。

  claude mcp add --transport http hubspot http://localhost:8765/mcp
  

• Claude Cowork — Claude Code の MCP 設定を共有するため、上記のコマンドを実行すると、そちらでもツールを利用できるようになります。

ヒント： デフォルトでは、モデルには 6 つのツールが表示され、検索 → 詳細確認 → 呼び出しを通じてすべてのエンドポイントを利用できます。エンドポイントごとに 1 つのツールを使うには、HUBSPOT_TOOL_MODE=all（690 個のツール）を設定し、HUBSPOT_INCLUDE_GROUPS（例：contacts,companies,deals,tickets,lists）で絞り込みます。設定ごとの実測値については、コンテキストの使用量を参照してください。

ビルド済みイメージを使いますか？

main へのプッシュごとに、すぐに実行できるイメージが GitHub Container Registry に公開されるため、ローカルでのビルドを省略できます。

docker run -d --name hubspot-mcp -p 127.0.0.1:8765:8765 --env-file .env \
  ghcr.io/ohneben/hubspot-mcp:latest

API 認証情報を取得する

推奨される方法は、HubSpot が従来のプライベートアプリに代わるものとして提供しているサービスキーを使用することです。

1. HubSpot で 設定 → 統合 → サービスキー（または 開発 → キー → サービスキー）を開き、キーを作成します。スーパー 管理者権限、または 開発者ツールへのアクセス 権限が必要です。
2. アシスタントにアクセスさせるスコープを選択します。スコープはツール グループと 1 対 1 で対応しています。レポート作成用の構成では読み取り スコープ（crm.objects.contacts.read、…）を付与し、変更が必要な箇所にのみ 書き込みスコープを追加します。
3. キー（pat-…）をコピーして、.env の HUBSPOT_ACCESS_TOKEN に設定します。プライベートアプリのトークンと同じようにベアラートークンとして送信されるため、ほかに変更は必要ありません。

注意事項：

• サービスキーはパブリックベータ版であり、プライベートアプリとは次の 3 つの重要な違いがあります。GraphQL はサポートされていません（HUBSPOT_ENABLE_GRAPHQL=false を設定してください）。ローテーション後も古いキーは 7 日間の猶予期間中有効です。また、機能レポートに表示されるスコープや使用状況の数値が不完全な場合があります。

• 既存のプライベートアプリトークンは引き続き利用できます。 HubSpot は従来のプライベートアプリの新規作成を停止します（既存のポータルでは 2026 年 10 月 26 日から、新規ポータルでは 2026 年 9 月 28 日から）。作成済みのアプリには影響しません。GraphQL ツールを利用する場合、ここでは引き続きプライベートアプリが唯一の選択肢です。

• OAuth アクセストークンも利用できます（自分で構築したアプリ向け）。ただし、有効期限は約 30 分で、このサーバーはトークンを更新しません。長時間稼働するサーバーには、サービスキーまたはプライベートアプリトークンが適しています。

• トークンによってポータルが決まるため、ポータル ID は不要です。

• EU データレジデンシー：ポータルが HubSpot の EU データセンターにある場合は、HUBSPOT_BASE_URL=https://api-eu1.hubapi.com を設定してください。

設定

すべて .env（.env.example からコピー）に設定します。

変数	必須	デフォルト	説明
HUBSPOT_ACCESS_TOKEN	✅	—	サービスキーまたは従来のプライベートアプリトークン（どちらも pat-…）、あるいは OAuth アクセストークンです。これがなくてもサーバーは起動し、ツールを一覧表示します（レジストリやインスペクター用）が、すべての呼び出しでセットアップ手順が返されます
HUBSPOT_BASE_URL	—	https://api.hubapi.com	EU データレジデンシーを利用するには https://api-eu1.hubapi.com を指定します
MCP_TRANSPORT	—	stdio	stdio または http（Docker イメージのデフォルトは http）
PORT	—	8765	HTTP リッスンポート
HOST	—	0.0.0.0	HTTP バインドアドレス
MCP_HTTP_PATH	—	/mcp	HTTP MCP ルート
MCP_AUTH_TOKEN	⚠️	(off)	/mcp へのアクセスに Authorization: Bearer <token> を必須にします。HOST がループバックアドレスでない場合は必須です。設定されていないと、サーバーは起動を拒否します。1.1.0 で MCP_SHARED_TOKEN から名称が変更されました
MCP_ALLOWED_HOSTS	—	(derived)	Host ヘッダーに指定できるホスト名をカンマ区切りで指定します。ループバックへのバインドではループバック名がデフォルトになり、リバースプロキシの背後ではチェックされません
MCP_ALLOW_INSECURE	—	0	ループバック以外へのバインドで、トークンなしで起動します。他の誰にも実際に到達できないポートの場合に限り使用してください
MCP_BODY_LIMIT	—	25mb	受け入れるリクエスト本文の最大サイズ
MCP_SESSION_TTL	—	1800	アイドル状態のセッションが破棄されるまでの秒数
MCP_MAX_SESSIONS	—	256	同時セッション数の上限。この数を超えると、最も長く使われていないセッションが破棄されます
HUBSPOT_MAX_REQUESTS	—	100	クライアント側のウィンドウごとのリクエスト数（0 でレート制限を無効化）
HUBSPOT_RATE_WINDOW_MS	—	10000	レート制限のウィンドウ（ミリ秒単位。デフォルト：100 リクエスト／10 秒）
HUBSPOT_SEARCH_MAX_REQUESTS	—	4	/search エンドポイントへの追加レート制限（0 で無効化）
HUBSPOT_SEARCH_RATE_WINDOW_MS	—	1000	検索のレート制限ウィンドウ（デフォルト：4 リクエスト／1 秒）
HUBSPOT_MAX_RETRIES	—	3	429／5xx／ネットワークエラー時の再試行回数
HUBSPOT_TIMEOUT_MS	—	30000	リクエストごとの試行タイムアウト
HUBSPOT_READ_ONLY	—	false	🟢 読み取り専用ツールのみを公開します
HUBSPOT_INCLUDE_GROUPS	—	(all)	指定したグループのみを公開します。contacts,deals のようなキーや、cms:* のような領域ワイルドカードを指定できます
HUBSPOT_EXCLUDE_GROUPS	—	(none)	指定したグループを非表示にします（同じ構文）
HUBSPOT_INCLUDE_BETA	—	true	ベータ版／開発者向けプレビュー API を含めます
HUBSPOT_TOOL_MODE	—	discovery	discovery（カタログ全体を扱う 3 つのメタツール）または all（エンドポイントまたはエンドポイントファミリーごとに 1 つのツール）
HUBSPOT_CAPABILITY_CHECK	—	true	起動時にトークンのスコープを読み取り、有料プランまたはベータ版のグループを確認します（API 呼び出しは最大で約 30 回）
HUBSPOT_ENABLE_GRAPHQL	—	true	CRM GraphQL クエリツールを公開します
HUBSPOT_GRAPHQL_URL	—	(derived)	GraphQL エンドポイントを上書きします
HUBSPOT_ENABLE_RAW_REQUEST	—	true	生リクエストのエスケープハッチを公開します（読み取り専用モードでは自動的に非表示）
HUBSPOT_MAX_RESPONSE_CHARS	—	0	N 文字を超えるレスポンスを切り詰めます（0 = 切り詰めない）
HUBSPOT_SPEC_DIR	—	(bundled)	別のディレクトリから OpenAPI ファイルと catalog.json を読み込みます

.env を変更した後は、docker compose up -d --force-recreate で再読み込みしてください。

npm run list-tools を実行すると（認証情報は不要）、カタログ全体、カテゴリごとの件数、フィルタリングに使用できるすべてのグループキーが表示されます。--names を追加すると、687 個すべてのツール名と、それぞれが呼び出すエンドポイントが一覧表示されます。

ツールの安全性カテゴリ

各ツールの説明は、以下のバナーのいずれかで始まり、対応する MCP アノテーションが付与されています。

バナー	ツール	エンドポイント	readOnlyHint	destructiveHint	意味
🟢 読み取り専用	274	348	true	false	GET — データを取得するだけです。安全です。
🟢 読み取り専用 · クエリ	28	95	true	false	検索／読み取りを行うPOST（オブジェクト検索、一括読み取り、エクスポート開始、トークンのイントロスペクション） — レコードは変更しません。
🟡 書き込み · データを作成	133	198	false	false	レコードを作成します（冪等ではないため、重複する場合があります）。
🟡 書き込み · 作成または更新	7	36	false	false	冪等なアップサート（一括アップサート、マーケティングイベントのアップサート）です。
🟡 書き込み · データを更新	131	215	false	false	既存コンテンツの公開、スケジュール設定、復元を含め、レコードや設定を直接変更します。
🟡 書き込み · レコードを関連付け	18	19	false	false	レコードを関連付けます（リストへの所属、v4 の関連付け）。元に戻せます。
🟡 書き込み · レコードの関連付けを解除	11	12	false	false	関連付けを解除します。元に戻せます — レコードは残ります。
🟡 書き込み · メッセージを送信	4	4	false	false	マーケティング／トランザクションメール、シーケンスへの登録、会話への返信です。
🟡 書き込み · 一括インポート	1	1	false	false	POST /crm/v3/imports — 数千件のレコードを作成／更新する場合があります。
🔴 破壊的 · データを削除	64	96	false	true	レコードを削除／アーカイブします（CRM のアーカイブは約90日間、復元可能です）。
🔴 破壊的 · 一括削除	10	42	false	true	一括アーカイブ — 1回の呼び出しで多数のレコードを処理します。
🔴 破壊的 · レコードをマージ	3	7	false	true	HubSpotではマージを解除できません。最初に両方のIDを確認してください。
🔴 破壊的 · GDPRに基づく完全消去	3	3	false	true	ごみ箱を経由せず、完全に削除します。

合計は 読み取り専用302 · 書き込み305 · 破壊的操作80 = エンドポイントツール687個 （443 · 485 · 148 = エンドポイント1,076個）で、さらに以下の3つのパワーツールがあります。アノテーションを尊重するホスト（Claudeを含む）は、destructiveHint ツールで確認を必須にし、readOnlyHint ツールを自動的に信頼できます。さらに制限したい場合は、HUBSPOT_READ_ONLY=true を設定すると、読み取り専用ツール302個（および🟢機能ツールとGraphQLツール）のみが公開されます。

領域別のカバレッジ（API数 / エンドポイント数：🟢読み取り / 🟡書き込み / 🔴破壊的操作 / ツール）

領域	API	🟢読み取り	🟡書き込み	🔴削除	エンドポイント	ツール
CRM	58	216	245	92	553	211
CMS	13	74	123	22	219	172
マーケティング	7	42	46	11	99	99
会話	3	18	11	3	32	32
自動化	3	17	10	4	31	31
Webhooks Journal	1	20	3	3	26	26
設定	3	14	9	1	24	24
ファイル	1	10	7	4	21	21
コミュニケーション設定	1	6	8	0	14	14
イベント	3	4	7	2	13	13
Webhooks	1	3	4	2	9	9
Data Studio	1	1	6	1	8	8
認証（OAuth）	1	3	2	2	7	7
アカウント	2	5	0	0	5	5
コマース	1	2	2	1	5	5
スケジューラー	1	3	2	0	5	5
メタ	1	4	0	0	4	4
ビジネスユニット	1	1	0	0	1	1
合計	102	443	485	148	1,076	687

## コンテキストの使用量

ツール一覧はモデルのコンテキストをどれくらい消費するのでしょうか？同梱の仕様に基づいて測定しています （tools/list の JSON ペイロード。トークン数 ≈ 文字数 ÷ 3.6）：

構成	ツール数	ペイロード	≈ トークン数
検出モード（デフォルト）	6	0.01 MB	~2k
HUBSPOT_TOOL_MODE=all	690	1.33 MB	~370k
all + 読み取り専用	304	0.38 MB	~104k
all + CRM コアプリセット¹	85	0.13 MB	~36k
all + CRM コアプリセット¹ + 読み取り専用	33	0.04 MB	~12k

検出モードでは、hubspot_get_endpoint による各検索で、モデルが要求したスキーマだけが追加されます。一般的なエンドポイントでは約 350 トークン、最も大きな CMS ページ本文では最大 ~12k トークンです。

_{¹ HUBSPOT_INCLUDE_GROUPS=contacts,companies,deals,tickets,lists,properties,associations,pipelines,crm-owners,notes,tasks,calls,emails,meetings}

次のように読み取れます。

• 検出モードでも対応範囲は失われません。1,076 個すべてのエンドポイントを、検索 → 詳細確認 → 呼び出しの流れで引き続き利用できます。モデルが初めてエンドポイントを使う際に、追加の呼び出しが 1～2 回必要になるだけです。
• ツール検索／遅延読み込みに対応したクライアント（Claude Code、claude.ai のコネクター）では、ツール定義が必要に応じて読み込まれるため、HUBSPOT_TOOL_MODE=all が適しています。HUBSPOT_INCLUDE_GROUPS プリセットや HUBSPOT_READ_ONLY=true を指定して対象を絞ることもできます。
• レスポンスもコンテキストを消費します。 HUBSPOT_MAX_RESPONSE_CHARS（例：40000）を設定して特に大きなレスポンスを制限し、CRM の読み取りでは必要な properties だけを要求してください。
• インラインスキーマが大きすぎる問題には、すでに対処済みです。再帰的な構造を持つ極端に大きなスキーマ 4 つ（リストフィルター、ワークフロー定義。完全にインライン化するとそれぞれ約 1.7 MB）は、最上位の階層を維持したまま 24 KB 以下に抑えられます。入力スキーマからは例と本文独自のフィールドより後にある説明文も削除されますが、すべてのフィールド、型、列挙値、必須項目のリストは維持されます。

強力なツール

生成されたエンドポイントツールのほかに、サーバーには手作業で構築されたツールが 4 つあります。

• hubspot_get_capabilities 🟢 — 上記で説明したアクセスレポートです。新たな API 呼び出しを行わずに起動時のチェック結果を返します。refresh: true を指定すると再実行します。
• hubspot_graphql_query 🟢 — HubSpot の CRM GraphQL API（POST /collector/graphql）です。HubSpot はミューテーションを公開していないため、クエリー専用として設計されており、読み取り専用モードでも引き続き利用できます。collector.graphql_query.execute スコープと Marketing/Content Hub Pro 以上が必要です。
• hubspot_api_request 🔴 — HubSpot ホスト上の任意のパスを呼び出すための、制限のない手段です（新しいベータ版や未公開の領域など）。同じ認証の挿入、スロットリング、再試行が適用されます。読み取り専用モードでは非表示になります。
• 検出モード（デフォルト）— 687 個のエンドポイントツールを、同じレジストリ上で hubspot_search_endpoints → hubspot_get_endpoint → hubspot_invoke_endpoint に置き換えます。すべてのフィルター（グループ、ベータ版、読み取り専用）は引き続き適用されます。読み取り専用モードでは、書き込みがレジストリに含まれないため、呼び出しツールから書き込み処理に到達することは物理的にできません。

1.x からのアップグレード

2.0 では、HubSpot がオブジェクトタイプごとに繰り返し提供しているエンドポイントを、セレクター引数を持つ1つのツールに統合しました。すべてのエンドポイントには引き続きアクセスでき、同じリクエストを送信します。変更されるのはツール名と一部の引数名のみです。ツール名を指定している保存済みプロンプト、クライアントの許可リスト、権限ルールを更新してください。HUBSPOT_INCLUDE_GROUPS / HUBSPOT_EXCLUDE_GROUPS のグループキー（contacts、deals、pages、…）に変更はありません。

1.x のツール	2.0 のツール	引数
contacts_list、deals_list、tickets_list、… custom_objects_list	crm_objects_list	objectType: "contacts"（または "deals"、"0-3"、カスタムの "2-12345"、…）
<type>_get、<type>_update、<type>_archive（一部は<type>_delete）	crm_objects_get、crm_objects_update、crm_objects_archive	objectType。レコードIDはcontactId、dealId、…ではなくobjectIdです
<type>_create、<type>_search、<type>_merge、<type>_batch_read / _create / _update / _upsert / _archive	crm_objects_create、crm_objects_search、crm_objects_merge、crm_objects_batch_*	objectType
partner_clients_associations_*、partner_services_associations_*	crm_objects_associations_list / _create / _delete	objectType: "partner_clients" または "partner_services"、objectId
pages_landing_*、pages_site_*	cms_pages_*、例：cms_pages_draft_push_live	pageType: "landing" または "site"
一覧取得、取得、アーカイブ、一括読み取り／更新／アーカイブ、多言語対応のposts_blogs_*、authors_blogs_*、tags_blogs_*	cms_blog_*、例：cms_blog_list	blogResource: "posts"、"authors"、または"tags"

変更なし：1つのタイプにしかないエンドポイント（contacts_gdpr_delete、ランディングページのフォルダー、ブログ投稿の下書きとリビジョン、リソースごとに本文が異なるブログの作成／更新）。npm run list-tools -- --names を実行すると、すべてのツールと呼び出すエンドポイントが表示されます。既存コンテンツを公開、予約、復元する POST エンドポイントは、データを作成 ではなく🟡 データを更新 と表示されるようになりました。

デフォルトも2つ変更されています。HUBSPOT_TOOL_MODE は discovery になりました（エンドポイントツール自体を公開するには all に設定してください）。また、サーバーは起動時にアクセスチェックを実行します。起動ごとに最大で約30回の API 呼び出しが発生します（HUBSPOT_CAPABILITY_CHECK=false で無効にできます）。

ソースから実行する（stdio、Docker 不要）

Claude Desktop で従来の stdio モードを使いますか？ローカルでビルドしてください。

npm install
npm run build

次に、claude_desktop_config.json でコンパイル済みのエントリーポイントを Claude Desktop に指定します。

{
  "mcpServers": {
    "hubspot": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/Hubspot-MCP/dist/index.js"],
      "env": {
        "MCP_TRANSPORT": "stdio",
        "HUBSPOT_ACCESS_TOKEN": "pat-na1-…"
      }
    }
  }
}

仕様を最新の状態に保つ

spec/ 配下のバンドルファイルが、ツールの信頼できる情報源です。これらのファイルは、HubSpot 独自の公開 API インデックス （https://api.hubspot.com/public/api/spec/v1/specs）から取得されます。このインデックスには、すべての公開 API と、バージョンごとの OpenAPI ドキュメントに加え、このサーバーがツールの説明に組み込む Hub とティアの要件 が記載されています。spec/catalog.json には、取得した内容（API、バージョン、ステージ、ベータフラグ、要件、ドキュメントへのリンク）が記録されています。

HubSpot の最新情報を取得して更新するには：

npm run fetch-specs   # rewrites spec/*.json + spec/catalog.json
npm run build && npm run list-tools

新しいエンドポイントは、コードを変更しなくても自動的に新しいツールになります。取得スクリプトは各 API の 安定版クラシックバージョン（v1/v3/v4）を優先し、HubSpot が日付付きバージョンまたはベータ版しか提供していない場合はそれらを使用します。実際に異なる複数のバージョンをまとめるため、いくつかの API はバージョンを固定しています（OAuth v1 + v3、Communication Preferences v3 + v4）。

開発

npm install
npm run build       # compile TypeScript → dist/
npm test            # run the Vitest suite (160 tests)
npm run list-tools  # print the categorized tool catalog (no credentials needed)
npm run fetch-specs # refresh spec/ from HubSpot's public API index

CI は Node 20 と 22 で、すべてのプッシュに対してビルドとテストを実行します。main へのプッシュでは、GitHub Container Registry に Docker イメージも公開されます。

注意事項と規約

• トランスポート：ローカルランチャーでは MCP_TRANSPORT=stdio（デフォルト）を使用します。 Docker イメージが実行する常時稼働の Streamable-HTTP サーバーでは、 MCP_TRANSPORT=http を使用します。
• ページング：CRM の一覧取得ツールはカーソルページングを使用します。limit と、 paging.next.after にある after カーソルを渡してください。必要なプロパティは properties パラメーターで指定してください（配列は繰り返しのクエリパラメーターになります）。
• セレクター：統合ツールでは、objectType（crm_objects_*）、 pageType（cms_pages_*）、または blogResource（cms_blog_*）を指定します。objectType には、名前（contacts、line_items）、objectTypeIds（0-3）、カスタムオブジェクトタイプ（2-12345）を指定できます。
• 検索：crm_objects_search などの *_search ツールには、filterGroups、sorts、query、 properties、limit、after を含む JSON の body を渡します。HubSpot はトークンごとに検索を 約 5 req/s に制限します。組み込みの検索スロットルにより、制限を超えないようにしています。
• バッチツール（crm_objects_batch_read、crm_objects_batch_create、…）は、多数のレコードを 操作する効率的な方法です。単一リクエストのループより優先して使用してください。
• 関連付け：レコードをリンクするには、v4 の関連付けツール（associations_*）を使用します。 必要に応じて、関連付けスキーマツールでラベルを指定できます。
• ファイルのアップロード：マルチパートツールでは、ファイルフィールドに {"fileName": "report.pdf", "contentBase64": "…"}（プレーンテキストの場合は content）を指定します。 その他のフィールドは通常のフォームフィールドとして送信し、オブジェクトは JSON 文字列として送信します。
• 削除はアーカイブ扱いです。CRM オブジェクトはごみ箱に保管されます（約 90 日間）。本当に 完全削除するのは、🔴 gdpr_delete の消去ツールとレコードのマージのみです。
• レート制限：HubSpot は 10 秒あたりのバースト上限（プライベートアプリはプランに応じて 100～200/10 秒、OAuth アプリは約 110/10 秒）と、1 日あたりの上限を適用します。サーバーは ウィンドウごとに HUBSPOT_MAX_REQUESTS で自己スロットリングし、それでも受信した 429 は Retry-After に従って再試行します。実際の使用状況はいつでも hubspot_get_capabilities で確認できます。
• リクエストボディ：書き込みツールには body 引数を渡します。スキーマは仕様から解決され、 モデルに表示されます（例：crm_objects_create は {"properties": {…}} を要求します）。
• ベータ API（開発者プレビュー／パブリックベータ）はデフォルトで含まれ、説明内で ⚠️ と表示されます。 HUBSPOT_INCLUDE_BETA=false にすると非表示になります。

セキュリティ

• アクセストークンは git-ignore 対象の .env にのみ保存されます。実際のシークレットを コミットしないでください。 トークンはスコープで許可された操作をすべて実行できます。漏えいした場合は、 Settings → Integrations → Service Keys（レガシートークンの場合は Private Apps）で有効期限を切らしてください。
• HTTP エンドポイントをこのマシンの外部にバインドする場合、認証なしでは起動できません。 MCP_AUTH_TOKEN（openssl rand -hex 32）を設定し、TLS の背後で Authorization: Bearer <token> ヘッダーとして送信してください。ループバックへのバインドでは トークンは不要ですが、Host ヘッダーのチェックによって DNS リバインディングからも保護されます。
• 破壊的なツール（削除／マージ／GDPR 消去）と送信ツール （マーケティングメールおよびトランザクションメール、シーケンス）には、適切なアノテーションが付いているため、 適切に動作するホストは実行前に確認を求めます。この確認を有効にしておくか、 HUBSPOT_READ_ONLY=true を設定して実行してください。
• 影響範囲は接続元で限定してください。サービスキーには、実際に必要なスコープだけを付与してください。 起動時のアクセスチェックと hubspot_get_capabilities で、不足しているスコープを確認できます。 アクセスチェック自体は読み取りのみを行います。

ポリシー全文と脆弱性の報告方法については、SECURITY.md を参照してください。

謝辞とライセンス

HubSpot 向けの非公式なコミュニティ統合であり、HubSpot とは提携しておらず、 同社による推奨も受けていません。Model Context Protocol を基盤としています。 ツールは HubSpot の公開 OpenAPI 定義から生成されています。MIT License の下でライセンスされています。