第10章：HubSpot MCP Server & AI 開発連携

10-1　MCP（Model Context Protocol）とは

AI エディタが外部ツールと通信するための標準プロトコルを理解する。

🔌 MCP の役割

MCP（Model Context Protocol）は Anthropic が策定した、AI アシスタントが外部ツール・データソースと安全に通信するためのオープンプロトコルです。 MCP サーバーを通じて AI は「ツール（Tool）」を呼び出せます。 HubSpot は公式の MCP Server（@hubspot/mcp-server）を提供しており、 Claude Code・Cursor などの AI エディタから自然言語で HubSpot の操作・照会・コード生成が可能になります。

MCP を使わない場合	MCP を使う場合
API リファレンスを調べながら手書きでコード	「コンタクトを検索して」と話しかけるだけ
プロパティ名・エンドポイントを都度確認	AI がポータルの実際のスキーマを参照して正確なコードを生成
テスト実行のために別ツールを開く	エディタ内でそのまま API を実行・結果確認
デバッグは手動でログを追う	AI がエラーを自動解析して修正案を提示

10-2　MCP Server のセットアップ

hs mcp setup コマンドで数分でセットアップ完了。

📋 前提条件

HubSpot CLI v8.0.0 以上（Node.js 20 が必要）
認証済みの HubSpot CLI（hs auth 完了）
AI エディタ：Claude Code・Cursor・VS Code（Copilot）のいずれか

Terminal — MCP Server セットアップ
# CLI のバージョン確認（8.0.0 以上が必要）
hs --version

# MCP Server を対話的にセットアップ
hs mcp setup

# ─── 対話プロンプト ────────────────────────────────# ? Which AI client do you want to configure?#   ❯ Claude Code#     Cursor#     VS Code## ? Which HubSpot portal do you want to connect?#   ❯ My Portal (12345678)#     Dev Sandbox (87654321)# ─────────────────────────────────────────────────# 完了メッセージ例# ✅ MCP Server configured for Claude Code# Config written to: ~/.claude/mcp.json

セットアップで生成される設定ファイル： hs mcp setup は各 AI クライアントの設定ファイルに MCP Server の接続情報を自動書き込みします。 Claude Code の場合は ~/.claude/mcp.json、 Cursor の場合は ~/.cursor/mcp.json、 VS Code の場合は .vscode/mcp.json（プロジェクト単位）に書き込まれます。

~/.claude/mcp.json — 生成される設定例

{
  "mcpServers": {
    "hubspot": {
      "command": "npx",
      "args": ["@hubspot/mcp-server"],
      "env": {
        "HUBSPOT_ACCESS_TOKEN": "pat-na1-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "HUBSPOT_PORTAL_ID":    "12345678"
      }
    }
  }
}
    

Terminal — MCP Server の動作確認
# MCP Server を手動起動してテスト
npx @hubspot/mcp-server

# ✅ HubSpot MCP Server started# Listening for MCP connections...# Connected to portal: My Portal (12345678)# Available tools: 47 tools loaded# 特定ポータルを指定して起動
HUBSPOT_ACCESS_TOKEN=pat-na1-xxx npx @hubspot/mcp-server
    

10-3　利用可能な MCP ツール一覧

HubSpot MCP Server が提供するツール（AI が呼び出せる操作）を把握する。

カテゴリ	ツール例	説明
CRM	`crm_search_contacts`	コンタクトを検索・フィルター
	`crm_create_contact`	コンタクトを作成
	`crm_get_deals`	商談一覧を取得
	`crm_update_deal`	商談プロパティを更新
スキーマ	`get_schemas`	全オブジェクトのスキーマ一覧
	`get_properties`	指定オブジェクトのプロパティ一覧
	`create_property`	カスタムプロパティを作成
CMS	`get_blog_posts`	ブログ記事一覧を取得
CMS	`get_hubdb_tables`	HubDB テーブル一覧と構造
ワークフロー	`list_workflows`	ワークフロー一覧
ワークフロー	`get_workflow_details`	ワークフローの詳細と実行履歴
Analytics	`get_analytics_summary`	ページビュー・コンバージョン集計
Analytics	`get_email_stats`	メール配信の開封・クリック率

10-4　Claude Code との連携実践

Claude Code で HubSpot MCP を使い、AI と対話しながら開発する具体的なフローを学ぶ。

🚀 Claude Code 起動と MCP 接続確認

ターミナルで claude コマンドを実行すると Claude Code が起動します。プロジェクトディレクトリで起動すると、そのコードベースのコンテキストも自動的に読み込まれます。 MCP Server が正しく設定されていれば、「HubSpot tools available」と表示されます。

実際のプロンプト例 — スキーマ確認

このポータルのカスタムオブジェクトをすべて一覧表示して、それぞれのプロパティ名と型も教えてください。

実際のプロンプト例 — データ調査

先週（2026年3月3日〜9日）に作成されたコンタクトのうち、ライフサイクルステージが "lead" のものを検索して、メールドメインごとに件数をまとめてください。

実際のプロンプト例 — コード生成

このポータルの "subscriptions" カスタムオブジェクトのスキーマを確認した上で、 status が "trial" で renewal_date が今月末までのレコードを全件取得し、 CSVに出力する Node.js スクリプトを書いてください。実際のプロパティ名を使って正確なコードを生成してください。

Terminal — Claude Code の基本的な使い方
# プロジェクトディレクトリで起動
cd ~/projects/hubspot-app
claude

# 特定のファイルをコンテキストに含めて起動
claude --context ./src/sync.js

# 1回だけ実行して終了（CI/CD などでの自動実行）
claude --print "HubSpot の contacts オブジェクトの全プロパティをJSON で出力して"

# MCP ツールの利用状況を確認
claude --mcp-debug
    

実際のプロンプト例 — デバッグ支援

src/webhook-handler.js の processEvent 関数で、 deal.propertyChange イベントが正しく処理されていません。このポータルの deal オブジェクトのプロパティ一覧を確認して、 dealstage の正確な値（closedwon など）を調べ、コードのどこに問題があるか特定してください。

10-5　Cursor との連携設定

Cursor IDE で HubSpot MCP を使うための設定と活用パターン。

~/.cursor/mcp.json — Cursor 用設定

{
  "mcpServers": {
    "hubspot": {
      "command": "npx",
      "args": ["@hubspot/mcp-server"],
      "env": {
        "HUBSPOT_ACCESS_TOKEN": "${env:HUBSPOT_ACCESS_TOKEN}",
        "HUBSPOT_PORTAL_ID":    "${env:HUBSPOT_PORTAL_ID}"
      }
    }
  }
}
    

環境変数の参照： Cursor の設定では ${env:変数名} の形式でシステム環境変数を参照できます。トークンをファイルに直書きするより安全です。.env ファイルや direnv と組み合わせると開発環境ごとに切り替えも容易です。

💡 Cursor での活用パターン

Cmd + K（インラインコード生成）：コード内で「// TODO: HubSpot で過去30日の成約をすべて取得」と書いて Cmd+K でそのまま実装

Cursor Chat（@ で MCP ツール参照）：チャットで「@hubspot でコンタクトスキーマを確認して、このデータモデルを設計して」

Composer（複数ファイルの自動編集）：「subscriptions カスタムオブジェクトに seat_count プロパティを追加するマイグレーションスクリプトを作成し、README も更新して」

10-6　AI 駆動開発フローの実践

MCP を活用した HubSpot 開発の典型的なワークフローを体験する。

1

ポータルの現状を AI に把握させる 「このポータルのカスタムオブジェクト・プロパティ構造・ワークフローを調べて、現在の CRM 設計を要約して」と依頼。AI が MCP ツールで実際のスキーマを取得・分析する。
2

要件を話し言葉で伝える 「Stripe からのサブスクリプションデータを subscriptions カスタムオブジェクトに毎日同期したい。どう実装するのがベストか提案して」と依頼。
3

実際のプロパティ名でコードを生成してもらう AI が MCP ツールでスキーマを確認し、正確なプロパティ名・型・API パスを使ったコードを生成。ドキュメントを調べる時間ゼロ。
4

その場で動作確認 「今生成したスクリプトをサンドボックスで実行して、結果を確認して」と依頼。AI が実際に API を呼び出し、レスポンスを確認して問題があれば修正する。
5

テストケースとドキュメントも生成 「このスクリプトのユニットテストと README セクションも書いて」と依頼。実装・テスト・ドキュメントを一気通貫で完成させる。

実践プロンプト例 — 完全な開発タスク

以下をお願いします： 1. このポータルの "subscriptions" カスタムオブジェクトの全プロパティを確認 2. status が "trial" かつ renewal_date が2026年3月末までのレコードを検索 3. 見つかったレコードのコンタクトに「トライアル期限アラート」メールを送るための HubSpot Workflow の設計案を提示 4. ワークフローをトリガーするための contact プロパティ更新スクリプトを作成コードは src/trial-alert.js に保存してください。

⚠ 本番ポータルへの誤操作に注意： AI が MCP ツールを通じて実際の API を呼び出すため、本番データへの書き込み・削除が即時実行されます。開発中は必ずサンドボックスポータルのトークンを使い、本番ポータルへの変更は慎重に確認してから実行してください。

10-7　複数ポータルの MCP 設定

開発・ステージング・本番の複数ポータルを MCP で切り替える。

~/.claude/mcp.json — 複数ポータル設定

{
  "mcpServers": {
    "hubspot-dev": {
      "command": "npx",
      "args": ["@hubspot/mcp-server"],
      "env": {
        "HUBSPOT_ACCESS_TOKEN": "pat-na1-dev-token",
        "HUBSPOT_PORTAL_ID":    "11111111"
      }
    },
    "hubspot-staging": {
      "command": "npx",
      "args": ["@hubspot/mcp-server"],
      "env": {
        "HUBSPOT_ACCESS_TOKEN": "pat-na1-staging-token",
        "HUBSPOT_PORTAL_ID":    "22222222"
      }
    },
    "hubspot-prod": {
      "command": "npx",
      "args": ["@hubspot/mcp-server"],
      "env": {
        "HUBSPOT_ACCESS_TOKEN": "pat-na1-prod-token",
        "HUBSPOT_PORTAL_ID":    "33333333"
      }
    }
  }
}
    

利用時の指定： Claude Code では「@hubspot-dev で…」「@hubspot-prod のスキーマを確認して」のようにサーバー名を @mention することで使用するポータルを明示できます。

10-8　この章のまとめ

✅ Chapter 10 チェックリスト

MCP（Model Context Protocol）の役割と HubSpot MCP Server の位置付けを理解した
hs mcp setup コマンドで Claude Code / Cursor / VS Code に MCP を設定できる
生成された mcp.json の構造を理解した
HubSpot MCP Server が提供するツール種別（CRM・スキーマ・CMS・ワークフロー）を把握した
自然言語でポータルのスキーマ照会・データ検索・コード生成を実行できる
「スキーマ確認 → 要件伝達 → コード生成 → 動作確認」の AI 駆動開発フローを実践できる
開発・本番の複数ポータルを mcp.json で管理できる
本番ポータルへの誤操作リスクを理解し、サンドボックス優先で開発できる

次章（Chapter 11）について：セキュリティ・パフォーマンス・本番運用を学びます。トークン管理・レート制限対策・エラーハンドリング・監視設計など、本番環境を安全かつ安定的に運用するための実践知識を解説します。

HubSpot MCP Server &AI 開発連携

🔌 MCP の役割

✅ Chapter 10 チェックリスト

HubSpot MCP Server &
AI 開発連携