ghl-context-mcp

意図的に小さく作られたGoHighLevel MCPサーバー。ツールは6つだけ。対象は1つの仕事に絞っている。つまり「今から話す相手が誰かを知ること」。

なぜ存在するのか

CRMにエージェントを載せたときにありがちな失敗は、ツールの表面が広く汎用的で、APIの生JSONをそのまま吐き出すことだ。その結果、モデルは誤ったツールを選び、誰も声に出さないようなフィールドでコンテキストウィンドウを消費し、時にはレコードを捏造したり上書きしたりする。このサーバーは逆の賭けを取っている。ツールは6つだけ、各ツールはエージェントが相手に話しかけるその瞬間に合わせている。返す各フィールドは、人が実際に口に出すか、次回呼び出しでエージェントがそのまま渡すものだ。日付計算もサーバープ自身で行い、書き込みをオンに切り替えまで無効にしている。狭いサーフェースが広サーフェースに勝る、という主張は測定可能であり、それを測るための伴わ: mcp-tool-surface-bench の`構築を進めっている。

Related MCP server: GHL MCP Server

ツール

レスポンスごとのトークン上限で、応答がそれ以上になるとビルドを落下すテストで強制しています。この「トークン」の意味は DESIGN.md を参照してください。

使用方法

This is an MCP server. 想定ユーザーは端末の人のではなくAIエージェントです。サーバをあ건ng代理（Claude Code、Claude Desktop、またはMCP対応ランタイム）に接続し、自然言語でエージェントに話しかけます.Resolution の判断はエージェエント側：連絡先の解決、その人の文脈を取り出す。

チーム向けクイックスタート（Claude Code）

1. リポジトリをクローンして、インストールしてビルドする：

   npm install && npm run build

2. 認証情報を追加する：

   cp .env.example .env
   # then edit .env and fill in GHL_PIT and GHL_LOCATION_ID

3. Claude Code でフォルダを開く。Claude Code はチェックイン済には .mcp.json を読み取り、ghl-context サーバーを提示する。その後一度承認すればいい。サーバーは起動時に .env を読み込むに入っているため、設定ファイルにトークンが書かれるこるはない。

4. 会話は、営業担当が一日の始まりにエージェントと話すように行う：

   今日はMarcus HallowayとPriya Nairに電話します。各人の電話する前に事前ブリーフィングを。

エージェントは各連絡先を解決し、タイムライン、パイプライン内位置、今後の予約を取り出し、ブリーフィグを返します。

他のMCP対応クライアント

この Stdio 経由で任意のMCPクライアントを、この;サーバーに接続できます。 公開パッケージはクローンもビルドも不要です。Claude Desktop の場合、claude_desktop_config.json にを追加します：

{
  "mcpServers": {
    "ghl-context": {
      "command": "npx",
      "args": ["-y", "ghl-context-mcp"],
      "env": {
        "GHL_PIT": "pit-...",
        "GHL_LOCATION_ID": "your-sub-account-id"
      }
    }
  }
}

公開パッケージの代わりにローカルチェックアウトを動く、command に node を設定し、args にビルド済みの dist/index.js を設定します。

環境変数

トークンは Settings、Integrations、Private Integrations の顺にて作成し、scope は contacts.readonly, contacts.write, opportunities.readonly, opportunities.write, calendars.readonly を指定します。

引入显示 without a client

MCPクライエントがない場合でも、リーポジトリに球端末デモ me が同梱されています。エージェントと同様のシーケンスを実行して、ブリーフィングを出力：

npm run brief -- "Marcus Halloway"

あはデモであり、価値を示すためのものです。製品は、上記のエージェント接続です。

ソースから

npm install
npm run build
npm test

npm test は認証情報がなくても成功します。実機チェックの npm run live-check と npm run live-write-check は、実際は .env が必要です。

レスポンスの形状

男の解：反映された連絡先：

{
  "resolution": "exact",
  "contact": {
    "contact_id": "NnAyKFnTSAVKg1amAArO",
    "name": "Marcus Halloway",
    "primary_phone": "+15551230010",
    "primary_email": "marcus.halloway@example.com",
    "tags": ["synthetic-seed"],
    "owner": null,
    "last_activity_at": null,
    "last_activity_summary": null
  }
}

曖昧な一致の場合、推測ではなく候補を返します：

{
  "resolution": "ambiguous",
  "candidates": [
    {
      "contact_id": "...",
      "name": "Jordan Wells",
      "primary_phone": "+15551230012",
      "primary_email": "jordan.wells@example.com",
      "last_activity_at": null
    },
    {
      "contact_id": "...",
      "name": "Jordan Wells",
      "primary_phone": "+15551230013",
      "primary_email": "jordan.wells.cpa@example.com",
      "last_activity_at": null
    }
  ],
  "disambiguate_by": ["email", "primary_phone"],
  "instruction": "Ask the user which one, or call again with the exact email or phone."
}

曖昧さは成功として扱います。エラーに当たったエージェントは停止しますが、候補リストを渡されたエージェントは続行して、どこの連絡先を指しているかをユーザーに選びます。

エラー

エラーはすべて形は同じ1種類です。未加工のHTTPステータスをモデルが目にすることはありません。

設計メモ

サーバーはこの8つの通則りの上に成り立っています。各1行にまとめた。それの「どのような」「どのようなもの」を含む長編は DESIGN.md にあります。

1. ツールごとに1つの仕事。説明文に「and」が必要なら、それは2つツールに分ければばつ.

2. 説明はモデルために書く：いつ使うか、いつ使わないか、そして混同しやすい類似ツールも明して.

3. の生形LRを外部へ持ち出さない。テストで強制される。

4. エラーは命令形の指示であり、有効な選択肢を列挙する。

5. どの応答にもトークン上限があり、ビルドを終えるテストで強制している。

6. サー、計算をする。経過日数・所要時間・相対時刻・回数など。

7. 書き込みは直している依存する状態を点検し、一致しない場合があります。

8. 書き込みは GHL_ALLOW_WRITES=true でない限り無効である。

やらないこと

意図した「切り離し」だ。

制限

単一のロケーション（サブアカウント）のみ。Private Integration Token 認証のみ、OAuth は非対応。ページネーションはツールごとの上限に制限される。停滞検出は意味を成すのにデータ量が要り、現状 GoHighLevel がステージ履歴を出さないため、固定フォールバックも使っている。電話番号一致は米 mを対象にしている。トークン上限は近似で、Claude tokens と厳密には一致しません。GoHighLevel の読み取りは、書取りよりも約1秒遅れて有効になる。検証されたアカウント形状は1種類。

ライセンス

MIT。