GoHighLevel MCP Server

LLMエージェントにGoHighLevel CRMの操作制御を提供するModel Context Protocolサーバーです。114個のツールを24モジュールにわたり提供し、顧客連絡先、パイプライン、カレンダー、メッセージ、請求、支払いをGoHighLevel API v2で操作できます。

問題

GoHighLevelは小規模エージェンシーにとってのシステムオブレコードです。すべての顧客、すべての予約、すべての請求書がそこにあります。実際に一日を消費させる作業は、単一のCRM操作ではなく、操作と操作の間を結び付ける処理です。撮影が確定したら、誰かが商談を作成し、正しいパイプライン段階へ移動し、正しい連絡先に対してカレンダースロットを予約し、請求書を下書きし、メモを残さなければなりません。各ステップは30秒のクリック作業であり、この一連の流れは週に何度も実行されます。

この一連の流れこそ、CRMにアクセスできればエージェントが実行できることです。このサーバーはそのアクセス手段です。GoHighLevelを型付きで注釈付きのツールとして公開することで、エージェントは数文の指示からプロセス全体を実行できます。一方で破壊的な操作や外部へ向けた操作は、承認のために可視化されたままです。

Related MCP server: GoHighLevel MCP Server

アーキテクチャ

24個のツールモジュールは、stdioを介して単一のMcpServerに登録されます。すべては単一のghlRequest()を経由し、認証、必須のVersionヘッダー、クエリ文字列の組み立て、エラー整形を担当します。モジュールは起動時にGHL_DISABLED_MODULESで切り替え可能です。これは一見したよりも重要で、114個のツール定義は、エージェントがユーザーのリクエストを1語も読む前に、コンテキストウィンドウのかなりの量に相当します。予約だけを実行するデプロイは、6個のモジュールだけを登録して残りをスキップできます。

  MCP host (Claude Desktop / Claude Code)
          | stdio (JSON-RPC)
  +-------v--------------------------------------------+
  |  index.ts   MODULES registry, GHL_DISABLED_MODULES  |
  +-------+--------------------------------------------+
          |
  +-------v-----+ +---------------+ +-----------+ ......  24 modules
  |  contacts   | | opportunities | | invoices  |
  +-------+-----+ +-------+-------+ +-----+-----+
          |               |               |
          |               |         +-----v--------------+
          |               |         | billing-helpers.ts |
          |               |         |  businessDetails   |
          |               |         |  contactDetails    |
          |               |         |  sender resolution |
          |               |         +-----+--------------+
          +-------+-------+---------------+
                  |
        +---------v----------------------------+
        |  client.ts  ghlRequest()             |
        |   Bearer token + Version header      |
        |   status-specific error hints        |
        +---------+----------------------------+
                  |
          services.leadconnectorhq.com

すべての書き込みツールにはMCP注釈が付いており、17個はdestructiveHintとしてマークされています。また、ghl_send_message / ghl_send_invoiceは実際に顧客に連絡を取るため、外部向けとしてフラグ付けされます。ホストは呼び出しを承認する前にこれらを提示します。これは、請求書を作成するだけのエージェントと、偶発的に顧客に送信するエージェントの違いとなります。

本当に難しい部分

請求書の作成です。エンドポイントはbusinessDetailsとcontactDetailsのブロックを必要とし、ドキュメントは両方を過小評価しています。ドキュメントに従ってcontactIdと少数の明細項目を渡すと、どのフィールドなのかを述べないバリデーションエラーが返ります。両方のブロックは完全な状態で必須であり、さらにbusinessDetails.phoneNoとcontactDetails.phoneNoは必須に、メールアドレスはあるが電話番号がない連絡先には請求書を発行することができません。

さらに悪いことには、値は画面が生成したものと一致しなければなりません。そうしないと、APIで作成された請求書は手作業で作成された請求書と異なる表示になります。ロゴが異なる、条件が漏れる、番号が間違うなどです。このようなデフォルト値は、想定される場所であるロケーションプロフィールにはありません。GET /invoices/settingsの内側にあり、UIが事前入力されるのと同じソースです。

src/tools/billing-helpers.tsが両方のブロックを解決するため、ツールはcontactIdだけを渡せれば済みます。ビジネス詳細は4階層でフォールバックします。呼び出しごとの引数、GHL_BUSINESS_*環境変数、保存済みの請求設定、ロケーションプロフィールです。各階層は、前の階層が空にした項目だけを埋めます。連絡先詳細は取得して組み立てられ、nameはフルネーム、名＋姓、会社名、メールアドレス、電話番号の順にフォールバックします。GoHighLevelは空の名前を拒否する上、実際のCRMレコードでは名前が欠落していることがしばしば存在するためです。どちらのパスでも、GHSLの不透明な422を表示するのではなく、欠落しているフィールドとその供給方法を明示するメッセージをスローします。各検索はロケーションごとにメモ済み化されるため、10件の請求書のバッチは設定取得が10回ではなく1回で済みます。

異なるならどうするか

1. テストがない。 4,000行、ゼロ。billing-helpersのフォールバックチェーンは、フィクスチャデータだけを対象にした純粋なロジックです。リポジトリ内で最もテストしやすく、誤ると最もコストが高くなります。失敗の形が顧客に送られる不正な請求書となるためです。

2. 429に対するリトライがない。 ghlRequestは呼び出し元に「レート制限されました。短時間あけて再試行してください」と伝えて、それ後リトライしません。バックオフはエージェントの判断ではなくクライアント側に置くべきです。

3. キャッシュは無効化を持たないモジュールレベルの可変マップである。 ホストが自由に再起動するstdio用途のサーバーには正しいが、これが長時間実行という長期間プロセスになると不正確になります。ビジネスプロフィールの編集が反映されないでしょう。

4. レスポンスは全体を通してRecord<string, unknown>である。 GoHighLevelはOpenAPIスペックを公開しているので、それからタイプを生成すればランタイムの予期しない問題の多くをコンパイルエラーに変えられます。

5. **1つのサーバーに114ツールは多い。**モジュールトグルは回避策であって修正ではありません。より良い形は、小さいツールセットと検出メカニズムを合わせ、エージェントが使用していない分だけコストを支払うことです。

セットアップ

Node.js 20以上とGoHighLevelアカウントが必要です。

1. プライベート統合トークンを作成する

設定 → プライベート統合 → 新規統合作成します。 使用するツールに対応するスコープを有効にします。最低限：

contacts.readonly、contacts.write、opportunities.readonly、opportunities.write、calendars.readonly、calendars/events.write、conversations.readonly、conversations/message.write、invoices.readonly、invoices.write、products.readonly、products.write、locations/customFields.readonly、workflows.readonly

コピーしてください。pit-で始まります。

2. Location IDを確認する

設定 → ビジネスプロフィール、またはダッシュボードのURLから確認します： .../location/<LOCATION_ID>/...

3. ビルド

git clone <this-repo>
cd ghl-mcp
npm install
npm run build

4. MCPホストに登録する

{
  "mcpServers": {
    "gohighlevel": {
      "command": "node",
      "args": ["/absolute/path/to/ghl-mcp/dist/index.js"],
      "env": {
        "GHL_API_KEY": "pit-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "GHL_LOCATION_ID": "your-location-id"
      }
    }
  }
}

ホストを再起動します。サポートされているすべての変数（請求書のビジネスブロックやモジュールのトグルを含む）は .env.example を参照してください。

ホストなしでサーバーを試すには：

GHL_API_KEY=pit-... GHL_LOCATION_ID=... npm run inspect

「オートメーションのビルド」についての注意

GoHighLevelのAPIはワークフローロジックを作成できません。ビジュアルビルダーはUI専用です。サポートされている方法は、UIでワークフローを一度ビルドし、ghl_list_workflowsでIDを見つけ、ghl_add_contact_to_workflowで連絡先を登録することです。

ツール参照

ライセンス

MIT — LICENSEを参照してください。GoHighLevelとは関係なく、また承認を受けているものではありません。