HubSpot

@mindstone/mcp-server-hubspot

CRM 操作（コンタクト、会社、取引、チケット、リード、タスク、メモ、関連付け）、プロパティとオーナー、マーケティング／リスト、ワークフロー、ナレッジベースの検索、ファイル操作に対応した HubSpot MCP サーバーです。

ホストが OAuth を制御するマルチアカウント対応の HubSpot MCP です。ファイルのアップロードをサンドボックス化し、新しいレコードすべてに作成元を示すラベルを付けます。

ステータス

• バージョン： 0.4.1 · npm
• 認証： OAuth（ホストによる制御）(HUBSPOT_CLIENT_SECRET)
• ツール： 106（CRM オブジェクト、関連付け、マーケティング、ファイル、ワークフロー、会話）
• 対象： クラウド API
• 機械可読： STATUS.json

開発の背景

HubSpot は公式 HTTP MCP サーバーを公開しており（2026 年初頭にパブリックベータを発表）、コミュニティ製の HubSpot MCP もいくつか存在します。このコネクターを開発した際に必要だったのは、別のものでした。ユーザーのマシン上でのみ動作するローカルサーバーで、複数の HubSpot アカウントを同時にサポートし、各アカウントの認証情報をそれぞれ専用のファイルに保存し、AI エージェントが作成したレコードを見分けられるよう新しいレコードにラベルを付け、ファイルのアップロード先をディスク上の単一のワークスペースフォルダーに制限するものです。既存の選択肢ではこれらすべてを満たせなかったため、独自に開発し、独自のセキュリティレビューを実施しました。

やり取りの例

「HubSpot で Acme Corp を探し、CTO とすばらしい電話会議ができたというメモを記録して、次の火曜日にフォローアップしてください。」

ホストが呼び出すツール：

1. search_hubspot_companies — 名前で Acme Corp を検索し、会社 ID を返します。
2. create_hubspot_note — 会社のレコードにメモを記録します。
3. create_hubspot_task — 会社に関連付けて、次の火曜日が期限のフォローアップタスクをスケジュールします。

応答（抜粋）：

{
  "company": { "id": "12345678901", "name": "Acme Corp" },
  "note": {
    "id": "9876543210",
    "createdAt": "2026-05-19T14:02:11Z",
    "body": "Great call with CTO — discussed Q3 rollout."
  },
  "task": {
    "id": "5566778899",
    "subject": "Follow up with Acme Corp",
    "dueDate": "2026-05-26T16:00:00Z"
  }
}

要件

• Node.js 20+
• npm
• HubSpot OAuth フローを実行し、アカウントごとの認証情報を ${HUBSPOT_CONFIG_DIR}/credentials/*.token.json に書き込むホストアプリケーション。このサーバーはこれらのファイルを読み込みます。ローカルの OAuth コールバックは実行しません。
• ファイルアップロードツールを使用する場合は、書き込み可能な MCP_WORKSPACE_PATH ディレクトリが必要です。

ワンクリックインストール

ボタンをクリックすると、ホストから次の値を入力するよう求められます：HUBSPOT_CONFIG_DIR、HUBSPOT_ACCOUNT_EMAIL、HUBSPOT_CLIENT_ID、HUBSPOT_CLIENT_SECRET、HUBSPOT_SOURCE_LABEL、HUBSPOT_REQUEST_TIMEOUT_MS。

{
  "mcpServers": {
    "HubSpot": {
      "command": "npx",
      "args": [
        "-y",
        "@mindstone/mcp-server-hubspot"
      ],
      "env": {
        "HUBSPOT_CONFIG_DIR": "",
        "HUBSPOT_ACCOUNT_EMAIL": "",
        "HUBSPOT_CLIENT_ID": "",
        "HUBSPOT_CLIENT_SECRET": "",
        "HUBSPOT_SOURCE_LABEL": "HubSpot MCP",
        "HUBSPOT_REQUEST_TIMEOUT_MS": "60000"
      }
    }
  }
}

クイックスタート

インストールとビルド

cd <path-to-repo>/connectors/hubspot
npm install
npm run build

npx（公開後）

npx -y @mindstone/mcp-server-hubspot

ローカル

node dist/index.js

設定

このサーバーは、ホストが調整する OAuth を前提に設計されています。ディスク上のホスト管理認証情報を読み込みます。

必須の環境変数

• HUBSPOT_CONFIG_DIR — accounts.json と credentials/*.token.json を含む設定ディレクトリです。
• HUBSPOT_ACCOUNT_EMAIL — このプロセスで使用するアカウントの選択子です（HubSpot アカウントごとに MCP プロセスを 1 つ起動します）。
• MCP_WORKSPACE_PATH — ローカルファイル用ツール（upload_hubspot_file、attach_file_to_record）のワークスペースルートです。

OAuth ブリッジ変数（ホストから注入）

• HUBSPOT_CLIENT_ID
• HUBSPOT_CLIENT_SECRET
• HUBSPOT_SOURCE_LABEL（任意）— 新しいレコードで使用するソース表示ラベルを上書きします（デフォルト：HubSpot MCP）

これらの値がなくてもサーバーは起動します（未設定モード）が、認証済みの HubSpot API アクセスが必要なツールは、構造化された auth_required 応答を返します。

認証フロー

authenticate_hubspot_account は、構造化された auth_required 応答を返します：

{
  "status": "auth_required",
  "user_action": { "id": "hubspot.connect_account" },
  "agent_action": {
    "instruction": "Tell the user that HubSpot needs reauthentication. The host will open the OAuth flow in their browser; once complete, retry the original request."
  },
  "setupToolName": "authenticate_hubspot_account"
}

ホストはこの形式を認識し、ブラウザーでの OAuth フローを実行します。

ホスト設定の例

このサーバーは、ホストが調整する OAuth を前提に設計されています。ホストがアカウントごとの認証情報ファイルをディスクに書き込み、サーバーがそれを読み込みます。以下の例は環境変数の形式を示しています。ツール呼び出しが成功する前に ${HUBSPOT_CONFIG_DIR}/credentials/*.token.json を設定するのは、ホストアプリケーションの役割です。

Claude Desktop / Cursor

{
  "mcpServers": {
    "HubSpot": {
      "command": "npx",
      "args": ["-y", "@mindstone/mcp-server-hubspot"],
      "env": {
        "HUBSPOT_CONFIG_DIR": "/absolute/path/to/hubspot-config",
        "HUBSPOT_ACCOUNT_EMAIL": "[email protected]",
        "MCP_WORKSPACE_PATH": "/absolute/path/to/workspace",
        "HUBSPOT_CLIENT_ID": "your-hubspot-app-client-id",
        "HUBSPOT_CLIENT_SECRET": "your-hubspot-app-client-secret"
      }
    }
  }
}

ホストが ${HUBSPOT_CONFIG_DIR}/credentials/[email protected] を書き込むまでは、認証済みの HubSpot アクセスが必要なツールは、構造化された auth_required 応答を返します（上記の「認証フロー」を参照）。

ローカル開発（npm への公開は不要）

{
  "mcpServers": {
    "HubSpot": {
      "command": "node",
      "args": ["<path-to-repo>/connectors/hubspot/dist/index.js"],
      "env": {
        "HUBSPOT_CONFIG_DIR": "/absolute/path/to/hubspot-config",
        "HUBSPOT_ACCOUNT_EMAIL": "[email protected]",
        "MCP_WORKSPACE_PATH": "/absolute/path/to/workspace",
        "HUBSPOT_CLIENT_ID": "your-hubspot-app-client-id",
        "HUBSPOT_CLIENT_SECRET": "your-hubspot-app-client-secret"
      }
    }
  }
}

ツール（106）

アカウントと認証

• list_hubspot_accounts — 接続済みのHubSpotアカウントと認証ステータスを一覧表示します。
• authenticate_hubspot_account — HubSpotアカウントを接続するためのOAuthフローを開始します。
• complete_hubspot_auth — OAuthコールバックを待機し、認証情報を保存します。
• remove_hubspot_account — HubSpotアカウントを切断し、保存済みの認証情報を削除します（破壊的操作）。

コンタクト

• search_hubspot_contacts — クエリまたはプロパティフィルターでコンタクトを検索します。
• get_hubspot_contact — IDで単一のコンタクトを取得します。
• create_hubspot_contact — コンタクトを作成します（破壊的操作）。
• update_hubspot_contact — コンタクトのプロパティを更新します（破壊的操作）。
• delete_hubspot_contact — コンタクトを完全に削除します（破壊的操作）。

企業

• search_hubspot_companies — クエリまたはプロパティフィルターで企業を検索します。
• get_hubspot_company — IDで単一の企業を取得します。
• create_hubspot_company — 企業を作成します（破壊的操作）。
• update_hubspot_company — 企業のプロパティを更新します（破壊的操作）。
• delete_hubspot_company — 企業を完全に削除します（破壊的操作）。

取引

• search_hubspot_deals — クエリまたはプロパティフィルターで取引を検索します。すべての結果を取得するには、次のカーソルが返されなくなるまで、paging.next.after の after を指定して繰り返します。
• get_hubspot_deal — IDで単一の取引を取得します。
• create_hubspot_deal — 取引を作成します。hubspot_owner_id が必要です（破壊的操作）。
• update_hubspot_deal — 取引のプロパティを更新するか、ステージを変更します（破壊的操作）。
• delete_hubspot_deal — 取引を完全に削除します（破壊的操作）。

チケット

• search_hubspot_tickets — フィルターを使ってチケットを検索します。
• get_hubspot_ticket — IDで単一のチケットを取得します。
• create_hubspot_ticket — サポートチケットを作成します（破壊的操作）。
• update_hubspot_ticket — チケットのプロパティを更新します（破壊的操作）。
• delete_hubspot_ticket — チケットを削除します（破壊的操作）。

リード（Sales Hub Pro/Enterprise）

• search_hubspot_leads — クエリまたはプロパティフィルターでリードを検索します。
• get_hubspot_lead — IDで単一のリードを取得します。
• create_hubspot_lead — コンタクトに関連付けられたリードを作成します（破壊的操作）。
• update_hubspot_lead — リードのプロパティを更新します（破壊的操作）。
• delete_hubspot_lead — リードを完全に削除します（破壊的操作）。

タスク

• search_hubspot_tasks — フィルターを使ってタスクを検索します。
• get_hubspot_task — IDで単一のタスクを取得します。
• create_hubspot_task — タスクを作成します（破壊的操作）。
• update_hubspot_task — タスクのプロパティを更新します（破壊的操作）。
• delete_hubspot_task — タスクを削除します（破壊的操作）。

メモ

• search_hubspot_notes — 本文テキストまたはプロパティフィルターでメモを検索します。
• get_hubspot_note — IDで単一のメモを取得します。
• create_hubspot_note — メモを作成し、必要に応じてレコードに関連付けます（破壊的操作）。
• update_hubspot_note — メモのプロパティを更新します。例：本文を編集します（破壊的操作）。
• delete_hubspot_note — メモを完全に削除します（破壊的操作）。

カスタムオブジェクト

• search_hubspot_object — テナントが定義したカスタムオブジェクトを含む、任意のオブジェクトタイプのレコードを検索します（ネイティブの全文検索クエリ）。
• get_hubspot_object — IDで任意のオブジェクトタイプの単一のレコードを取得します。
• create_hubspot_object — 任意のオブジェクトタイプのレコードを作成します（破壊的操作）。カスタムオブジェクトには crm.objects.custom.write スコープが必要です。

関連付け

• create_hubspot_association — 2つのレコード間にラベルなしの関連付けを作成します（v3）（破壊的操作）。
• get_hubspot_associations — 指定したタイプのレコードに関連付けられた項目を一覧表示します。
• delete_hubspot_association — 2つのレコード間の関連付けを削除します（破壊的操作）。
• list_hubspot_association_labels — 2つのオブジェクトタイプ間で利用可能な関連付けラベルを一覧表示します（v4）。
• create_hubspot_labeled_association — 2つのレコード間にラベル付きの関連付けを作成します（v4）（破壊的操作）。

プロパティとスキーマ

• list_hubspot_properties — オブジェクトタイプのプロパティ定義を一覧表示します。
• get_hubspot_property — 単一のプロパティ定義を取得します。
• create_hubspot_property — オブジェクトにカスタムプロパティを作成します（破壊的操作）。
• update_hubspot_property — 既存のプロパティ定義を更新します（破壊的操作）。
• delete_hubspot_property — オブジェクトからプロパティをアーカイブします（破壊的操作）。
• list_hubspot_property_groups — オブジェクトタイプのプロパティグループを一覧表示します。
• create_hubspot_property_group — 新しいプロパティグループを作成します（破壊的操作）。

オーナー

• list_hubspot_owners — CRM レコードのオーナーになれる HubSpot ユーザーを一覧表示します。
• get_hubspot_owner — ID を指定して特定のオーナーの詳細を取得します。

パイプライン

• list_hubspot_pipelines — 営業／チケットのパイプラインとそのステージを一覧表示します。
• get_hubspot_pipeline — 特定のパイプラインとそのステージを取得します。

エンゲージメント（通話、ミーティング、メール）

• search_hubspot_calls — フィルターを指定して記録済みの通話を検索します。
• search_hubspot_meetings — フィルターを指定して記録済みのミーティングを検索します。
• search_hubspot_emails — 記録済みの 1 対 1 の営業メールを検索します（本文の取得には sales-email-read スコープが必要です。notes の警告は、データが秘匿されたこと、またはスコープを検証できなかったことを示します）。
• get_hubspot_call — ID を指定して単一の通話を取得します。
• get_hubspot_meeting — ID を指定して単一のミーティングを取得します。
• get_hubspot_email — ID を指定して単一のメールエンゲージメントを取得します。
• create_hubspot_call — 通話を記録し、任意でレコードに関連付けます（破壊的操作）。
• create_hubspot_meeting — ミーティングを記録し、任意でレコードに関連付けます（破壊的操作）。
• get_contact_engagements — コンタクトの最近の通話、メール、ミーティングを取得します。

製品

• search_hubspot_products — 製品カタログを検索します。
• get_hubspot_product — ID を指定して単一の製品を取得します。
• create_hubspot_product — カタログに製品を作成します（破壊的操作）。
• update_hubspot_product — 既存の製品を更新します（破壊的操作）。

明細項目

• search_hubspot_line_items — フィルターを指定して明細項目を検索します。
• get_hubspot_line_item — ID を指定して単一の明細項目を取得します。
• create_hubspot_line_item — 明細項目を作成し、任意で取引に関連付けます（破壊的操作）。

フォーム

• list_hubspot_forms — HubSpot のフォームを一覧表示します。
• get_hubspot_form — フォームの設定とフィールドを取得します。
• get_hubspot_form_submissions — フォームへの送信内容を取得します。

アナリティクス（Marketing Hub Pro／Enterprise）

• get_hubspot_analytics_report — ウェブサイトのトラフィックに関するアナリティクスレポートを取得します。

マーケティングメール

• list_hubspot_marketing_emails — マーケティングメールを一覧表示します。
• get_hubspot_marketing_email — マーケティングメールの詳細を取得します。
• get_hubspot_email_statistics — メールのパフォーマンスに関する集計統計を取得します。

リストとセグメント

• list_hubspot_lists — コンタクトのリスト／セグメントを一覧表示します。
• get_hubspot_list — リストの詳細とフィルター条件を取得します。
• list_hubspot_list_members — リストに含まれるコンタクト ID を取得します。
• add_hubspot_list_members — MANUAL／SNAPSHOT リストにレコードを追加します（破壊的操作。crm.lists.write が必要です）。
• remove_hubspot_list_members — MANUAL／SNAPSHOT リストからレコードを削除します（破壊的操作。crm.lists.write が必要です）。
• batch_read_hubspot_contacts — 1 回のリクエストで ID を指定して最大 100 件のコンタクトを取得します。

ナレッジベース（Service Hub Pro／Enterprise）

• list_hubspot_kb_articles — ナレッジベースの記事を一覧表示します（GraphQL）。
• get_hubspot_kb_article — ID を指定して単一の KB 記事を取得します。
• search_hubspot_kb_articles — サイト内検索で公開済みの KB 記事を検索します。

ファイル

• upload_hubspot_file — ローカルファイルを HubSpot のファイルマネージャーにアップロードします（破壊的操作。MCP_WORKSPACE_PATH が必要です）。
• import_hubspot_file_from_url — 公開 URL からファイルをファイルマネージャーにインポートします（破壊的操作）。
• get_hubspot_file — ファイルのメタデータを取得します。署名付きの閲覧可能な URL を任意で返します。
• delete_hubspot_file — ファイルマネージャーからファイルを削除します（破壊的操作）。
• attach_file_to_record — ファイルをアップロード／インポートし、ノート経由でレコードに添付します（破壊的操作。ローカルファイルのアップロード時は MCP_WORKSPACE_PATH が必要です）。

ワークフロー（v4 BETA。Marketing Hub Pro/Enterprise）

• list_hubspot_workflows — 自動化ワークフローの一覧を取得します。
• get_hubspot_workflow — ワークフローのアクション、トリガー、分岐を取得します。
• create_hubspot_workflow — 新しいワークフローを作成します（破壊的操作）。
• update_hubspot_workflow — ワークフローの設定を置き換えます（破壊的操作）。
• delete_hubspot_workflow — ワークフローを完全に削除します（破壊的操作）。
• activate_hubspot_workflow — ワークフローを有効にします（破壊的操作）。
• deactivate_hubspot_workflow — ワークフローを無効にします（破壊的操作）。
• enrol_in_hubspot_workflow — 特定のレコードをワークフローに登録します（破壊的操作）。

セキュリティに関する注意事項

• ファイル関連ツールでは、MCP_WORKSPACE_PATH と正規パスのチェックを使用して、ワークスペース内にアクセスを制限します。
• ローカルの認証情報はホスト管理のファイルから読み込まれ、アカウントは HUBSPOT_ACCOUNT_EMAIL によって固定されます。
• このサーバーはローカルの OAuth コールバックサーバーを実行しません。OAuth はホスト側で制御されます。
• ソース属性ラベルは新しい書き込みにのみ適用されます。既存の HubSpot レコードの内容が遡って書き換えられることはありません。
• HubSpot から返されるすべてのテキスト（レコードのプロパティ、ノート／エンゲージメントの本文、会話メッセージ、ナレッジベースの記事、フォーム送信内容、名前／ラベル）は、終了タグのブレークアウトをエスケープした <untrusted-content source="hubspot:…"> エンベロープで囲まれます。これにより、ツール出力を受け取るモデルは、第三者が作成したテキストを指示ではなくデータとして扱います。識別子、列挙値、URL、タイムスタンプ、ページネーションカーソルは、ツール間のラウンドトリップが機能するよう、そのまま保持されます。ただし、レコードの properties バッグ内では、プロパティ名を問わずすべての値がエンベロープで囲まれます（カスタムプロパティ名はテナントごとに定義されるため、信頼できません。レコード ID のラウンドトリップにはトップレベルの id を使用します）。サーフェスごとの例外（プロパティスキーマの name／groupName／オプションの value、フォームフィールドのバインディング）は、文書化されたレスポンス形式の範囲内に限定されます。
• OAuth アクセストークンは、トークン自体をパスとして指定するトークン情報エンドポイントを含め、すべてのリクエストログとエラー概要で秘匿されます。

ライセンス

FSL-1.1-MIT — Functional Source License, Version 1.1。将来的に MIT ライセンスとなります。このソフトウェアは 2030-04-08 に MIT ライセンスへ移行します。