HubSpot MCP Server

HubSpot MCP サーバー

HubSpot CRM とシームレスに連携し、AI アシスタントが HubSpot のデータを操作できる、強力な Model Context Protocol（MCP）サーバー実装です。

概要

この MCP サーバーは、HubSpot CRM API を操作するための包括的なツールセットを提供し、AI アシスタントで次のことが可能になります。

• HubSpot CRM でコンタクトや企業を作成・管理する
• 企業の詳細なアクティビティ履歴やエンゲージメントのタイムラインを取得する
• HubSpot インスタンス全体で最近のエンゲージメントデータにアクセスする
• 最近アクティブになった企業やコンタクトのリストを取得する
• AI アシスタントの画面を離れることなく CRM 操作を実行する

この MCP サーバーを使用する理由

• シームレスな AI 連携：AI アシスタントを HubSpot CRM のデータに直接接続できます
• CRM 操作の簡素化：自然言語コマンドで一般的な HubSpot タスクを実行できます
• リアルタイムのデータアクセス：HubSpot インスタンスから最新情報を取得できます
• 安全な認証：HubSpot の安全な API トークン認証を使用します
• 拡張しやすい設計：必要に応じて、HubSpot API の機能を簡単に追加できます

インストール

# Clone the repository
git clone https://github.com/lkm1developer/hubspot-mcp-server.git
cd hubspot-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

設定

このサーバーには HubSpot API アクセストークンが必要です。次の手順で取得できます。

1. HubSpot Developer Account にアクセスします
2. 必要なスコープ（contacts、companies、engagements）を設定したプライベートアプリを作成します
3. 生成されたアクセストークンをコピーします

トークンは次の2つの方法で指定できます。

1. 環境変数として指定する：

   HUBSPOT_ACCESS_TOKEN=your-access-token
   

2. コマンドライン引数として指定する：

   npm start -- --access-token=your-access-token
   

開発時は、プロジェクトのルートに .env ファイルを作成して環境変数を保存します。

HUBSPOT_ACCESS_TOKEN=your-access-token

使用方法

サーバーの起動

# Start the server
npm start

# Or with a specific access token
npm start -- --access-token=your-access-token

# Run the SSE server with authentication
npx mcp-proxy-auth node dist/index.js

SSE サーバーでの認証の実装

SSE サーバーは、認証に mcp-proxy-auth パッケージを使用します。認証を実装するには、次の手順に従います。

1. パッケージをインストールします。

   npm install mcp-proxy-auth
   

2. AUTH_SERVER_URL 環境変数に、API キー検証エンドポイントを設定します。

   export AUTH_SERVER_URL=https://your-auth-server.com/verify
   

3. 認証を有効にして SSE サーバーを実行します。

   npx mcp-proxy-auth node dist/index.js
   

4. SSE URL は次の場所で利用できます。

   localhost:8080/sse?apiKey=apikey
   

   認証には、apikey を実際の API キーに置き換えてください。

mcp-proxy-auth パッケージはプロキシとして次の処理を行います。

• SSE サーバーへのリクエストをインターセプトする
• 認証サーバーに対して API キーを検証する
• 認証済みのリクエストのみが SSE エンドポイントに到達できるようにする

AI アシスタントとの連携

この MCP サーバーは、Model Context Protocol に対応した AI アシスタントで動作するように設計されています。起動すると、互換性のある AI アシスタントが HubSpot CRM のデータを操作するために使用できるツールセットを公開します。

利用可能なツール

サーバーでは、次の強力な HubSpot 統合ツールを利用できます。

1. hubspot_create_contact

   • 重複をチェックして、HubSpot に新しいコンタクトを作成します
   • パラメーター：
     • firstname（string、必須）：コンタクトの名
     • lastname（string、必須）：コンタクトの姓
     • email（string、任意）：コンタクトのメールアドレス
     • properties（object、任意）：会社名、電話番号など、追加のコンタクトプロパティ
   • 例：

     {
       "firstname": "John",
       "lastname": "Doe",
       "email": "[email protected]",
       "properties": {
         "company": "Acme Inc",
         "phone": "555-123-4567",
         "jobtitle": "Software Engineer"
       }
     }
     

2. hubspot_create_company

   • 重複をチェックして、HubSpot に新しい会社を作成します
   • パラメーター：
     • name（string、必須）：会社名
     • properties（object、任意）：追加の会社プロパティ
   • 例：

     {
       "name": "Acme Corporation",
       "properties": {
         "domain": "acme.com",
         "industry": "Technology",
         "phone": "555-987-6543",
         "city": "San Francisco",
         "state": "CA"
       }
     }
     

3. hubspot_get_company_activity

   • 特定の会社の包括的なアクティビティ履歴を取得します
   • パラメーター：
     • company_id（string、必須）：HubSpot の会社 ID
   • メール、通話、ミーティング、メモ、タスクなどの詳細なエンゲージメントデータを返します

4. hubspot_get_recent_engagements

   • すべてのコンタクトと会社にわたる最近のエンゲージメントアクティビティを取得します
   • パラメーター：
     • days（number、任意、デフォルト：7）：遡って検索する日数
     • limit（number、任意、デフォルト：50）：返すエンゲージメントの最大数
   • 最近の CRM アクティビティをすべて時系列順に並べたリストを返します

5. hubspot_get_active_companies

   • HubSpot で最近アクティブだった会社を取得します
   • パラメーター：
     • limit（number、任意、デフォルト：10）：返す会社の最大数
   • 最終更新日順に並べた会社を返します

6. hubspot_get_active_contacts

   • HubSpot で最近アクティブだったコンタクトを取得します
   • パラメーター：
     • limit（number、任意、デフォルト：10）：返すコンタクトの最大数
   • 最終更新日順に並べたコンタクトを返します

7. hubspot_update_contact

   • HubSpot の既存のコンタクトを更新します（コンタクトが存在しない場合は無視します）
   • パラメーター：
     • contact_id（string、必須）：更新する HubSpot のコンタクト ID
     • properties（object、必須）：更新するコンタクトプロパティ
   • 例：

     {
       "contact_id": "12345",
       "properties": {
         "email": "[email protected]",
         "phone": "555-987-6543",
         "jobtitle": "Senior Software Engineer"
       }
     }
     

8. hubspot_update_company

   • HubSpot の既存の会社を更新します（会社が存在しない場合は無視します）
   • パラメーター：
     • company_id（string、必須）：更新する HubSpot の会社 ID
     • properties（object、必須）：更新する会社プロパティ
   • 例：

     {
       "company_id": "67890",
       "properties": {
         "domain": "updated-domain.com",
         "phone": "555-123-4567",
         "industry": "Software",
         "city": "New York",
         "state": "NY"
       }
     }
     

サーバーの拡張

このサーバーは簡単に拡張できるように設計されています。HubSpot API の機能を追加するには、次の手順を実行します。

1. src/hubspot-client.ts の HubSpotClient クラスに新しいメソッドを追加します
2. src/index.ts の setupToolHandlers メソッドに新しいツールを登録します
3. npm run build でプロジェクトを再ビルドします

ライセンス

このプロジェクトは MIT License のもとでライセンスされています。詳細は LICENSE ファイルをご覧ください。

キーワード

HubSpot、CRM、Model Context Protocol、MCP、AI アシスタント、TypeScript、API 統合、HubSpot API、CRM 統合、コンタクト管理、企業管理、エンゲージメント追跡、AI ツール