@aiwerk/mcp-server-ghl

エージェンシーがクライアントのセールスパイプライン、カレンダー、会話、キャンペーンを管理するために使用するCRMおよびマーケティング自動化プラットフォームであるGoHighLevel (GHL) API用のMCPサーバーです。

GHLの公式OpenAPI 3.0.0仕様から生成された、41ドメインにわたる569のツール。

Contacts       Opportunities   Conversations   Calendars      Invoices
Payments       Workflows       Campaigns       Forms          Surveys
Funnels        Blogs           Courses         Products       Store
Social Media   Ad Manager      SaaS API        Snapshots      Custom Fields

生成された理由

すべてのエンドポイント、HTTP動詞、パラメータ、フィールド名は、散文のドキュメントではなく公式仕様から取得されるため、ツールの表面がGHLが実際に受け入れるものから逸脱することはありません。仕様からはわからないこと、つまりどのエンドポイントがロケーショントークンではなくエージェンシーレベルのトークンを必要とするか、どのAPIバージョンをエンドポイントが期待するか、ドキュメントが必須とマークするのを忘れたフィールドは、手作業で追加されています。知っておくべきGHLのいくつかの点を参照してください。

Related MCP server: GoHighLevel MCP Server

インストール

npm install -g @aiwerk/mcp-server-ghl

Node.js 18以上が必要です。

認証

対象のロケーションで、Settings > Private Integrations の下にプライベート統合トークン (PIT) を作成します。PITは1つのロケーションにスコープされており、エージェンシー全体の資格情報ではありません。また、ほとんどのツールは、どのロケーションに対して動作しているかを知る必要があります。

export GHL_PIT_TOKEN="your-private-integration-token"
export GHL_LOCATION_ID="your-location-id"

使用方法

Claude Code

claude mcp add ghl \
  --env GHL_PIT_TOKEN=your-token \
  --env GHL_LOCATION_ID=your-location-id \
  -- npx -y @aiwerk/mcp-server-ghl

Claude Desktop

{
  "mcpServers": {
    "ghl": {
      "command": "npx",
      "args": ["-y", "@aiwerk/mcp-server-ghl"],
      "env": {
        "GHL_PIT_TOKEN": "your-token",
        "GHL_LOCATION_ID": "your-location-id"
      }
    }
  }
}

AIWerk ホステッドサービス

aiwerkmcp.comのカタログからインストールし、インターフェースでトークンを追加してください。ローカルでのセットアップは不要です。

安全機能

ドライラン

export GHL_DRY_RUN=1

すべての書き込み（POST/PUT/PATCH/DELETE）はGHLに到達する前に停止され、送信されるはずだったリクエストの説明を返します。読み取りは通常どおり機能します。

エージェンシー専用エンドポイントは素の401ではなく明確なエラーを返します

39のエンドポイント（スナップショット、SaaS API、エージェンシーOAuthトークン交換、カスタムオブジェクトの作成）はエージェンシーレベルのトークンを必要とします。ロケーションPITはこれらに対してGHLから本文に説明のない素の401を受け取りますが、サーバーはこれらのエンドポイントがどれかを知っており、トークンが不正または期限切れのように見せるのではなく、その旨のメッセージを返します。

locationIdは自動的に入力されます

PITはすでに1つのロケーションにスコープされているため、569のツールのうち430はlocationId（またはaltId/altType）をオプションパラメータとして受け入れます。呼び出し側のエージェントが指定しない場合、サーバーはGHL_LOCATION_IDにフォールバックします。これはまた、デフォルトが常にトークン自身のスコープと一致するため、別のアカウントからコピー＆ペーストされたIDによってツール呼び出しが誤って間違ったロケーションをターゲットにすることも防ぎます。

設定

ツールセットの絞り込み

デフォルトでは569のツールすべてが登録されています。より小さなサーフェスを好むクライアントは、サーバーを特定のドメインに制限できます（ドメイン名はハイフンで区切られます。例: social-media-posting、ad-manager）：

export GHL_ENABLED_TAGS="contacts,opportunities,conversations,calendars"

不明なドメイン名はサイレントに無視されるのではなく、起動時に報告されます。

知っておくべきGHLのいくつかの点

• APIバージョンはエンドポイントごとに異なり、グローバルではありません。 GHLはVersionリクエストヘッダー（2021-07-28または2021-04-15）を送信します。サーバーは各エンドポイントが実際に期待するものに基づいて呼び出しごとに設定します。間違ったバージョンはエラーではなく異なるレスポンス形状を静かに返すため、フォールバックできる単一のデフォルトはありません。29のエンドポイントはバージョンヘッダーをまったく送信しません。サーバーもそれに合わせます。

• ロケーションPITはエージェンシー専用エンドポイントを呼び出すことはできません。スコープを変更しても解決しません。 snapshots/*、saas-api/*、oauth/locationToken、oauth/installedLocations、およびカスタムオブジェクトの作成（POST /objects）にはエージェンシーレベルの資格情報が必要です。

• 公式仕様の11のエンドポイントはパスパラメータの宣言を省略しています（例: 一部のカレンダー/会話ルートのnoteId、ブログのpostId、連絡先のtype）。パラメータがパステンプレートで明確に使用されているため、ジェネレーターはこれらを必須の文字列フィールドとして埋めます。これは上流の仕様のギャップであり、ここで導入されたものではありません。

• レート制限はまだ実アカウントに対して測定されていません。 クライアントはGHLが送信するRetry-Afterを使用して429で再試行しますが、独自の数値で先制的にスロットルすることはありません。間違った想定制限はアカウントを過小使用するか、成功するはずの呼び出しを失敗させ始める可能性があります。

テスト

npm test          # unit tests, mocked fetch
npm run smoke      # read only, against a live account

開発

ツールレイヤーは生成されており、手動で編集してはなりません：

npm run gen-naming   # specification  ->  tool names
npm run gen-tools    # specification  ->  zod schemas and call sites
npm run build

ライセンス

MITライセンスです。LICENSEを参照してください。

AIWerkによって構築されました。GoHighLevel / HighLevel Inc.とは提携していません。