GoHighLevel API v2 とのシームレスな統合を実現するモデルコンテキストプロトコル(MCP)サーバー。 このサーバーは、AIアシスタントがGoHighLevelのCRM機能とやりとりすることを可能にします。

##特徴

• OAuth 2.0 認証**: 自動トークン管理によるフルOAuthフロー
• LXAgency または sub-account スコープ: エージェンシー (Company) トークンはそれぞれ管理します 自動エージェンシー→ロケーショントークン交換によるサブアカウント。サブアカウント (ロケーション) トークンは直接使用され、そのサブアカウントにロックされます
• 出発日 * 連絡先、会話、メッセージング、機会&機会 パイプライン、カレンダーと予約、フォーム、カスタムフィールドと値、 メモとタスク、ユーザー、ワークフロー — API の quirks を扱う型ツール
• [ghl_list_endpoints] + [ghl_request]]が到達 GoHighLevel v2 API全体(キュレーションツールよりも長い尾)、 自動トークンのルーティング、quirkの正規化および確認のgating 破壊的/影響力の高い書き込み
• 自動トークンがリフレッシュ**: トークンの有効期限をシームレスに処理
• MCP ツールとリソース**: 柔軟な統合のためのツールとリソースの両方

GoHighLevel MCP Server

A Model Context Protocol (MCP) server that provides seamless integration with the GoHighLevel API v2. This server enables AI assistants to interact with GoHighLevel’s CRM functionality, starting with comprehensive contact management.

Features

• 🔐 OAuth 2.0 Authentication: Full OAuth flow with automatic token management
• 🏢 Agency or sub-account scope: An agency (Company) token manages every sub-account via automatic agency→location token exchange; a sub-account (Location) token is used directly and is locked to that one sub-account
• 👥 Curated domains: Contacts, conversations & messaging, opportunities & pipelines, calendars & appointments, forms, custom fields & values, notes & tasks, users, and workflows — typed tools that handle API quirks
• 🌐 Full-surface gateway: ghl_list_endpoints + ghl_request reach the entire GoHighLevel v2 API (the long tail beyond the curated tools), with automatic token routing, quirk normalization, and confirmation gating on destructive/high-impact writes
• 🔄 Automatic Token Refresh: Handles token expiration seamlessly
• 🛠️ MCP Tools & Resources: Both tools and resources for flexible integration

Prerequisites

• Python 3.12+
• uv package manager (or pip)
• One of the following:
  • Standard Mode Configuration: Access via our hosted GoHighLevel app (coming soon)
  • Custom Mode Configuration: Your own GoHighLevel Marketplace App credentials

Getting Started - Installation

1. Clone the repository:

git clone https://github.com/basicmachines-co/open-ghl-mcp.git
cd open-ghl-mcp

2. Install dependencies:

uv venv
source .venv/bin/activate
uv pip install -r requirements.txt

3. Start the server:

python -m src.main

1. Configuration

Basic Machines team members: skip this — use the shared app credentials from 1Password and follow Team Setup instead of creating your own app.

For external/self-hosted use, create your own GoHighLevel Marketplace App:

1. Create your own GoHighLevel Marketplace App
2. Set the redirect URL to: http://localhost:8080/oauth/callback
3. Enable the scopes you want for the tools below (the server requests its full ALL_SCOPES set at authorization; the granted token is the intersection of that and the scopes your app enables)

2. Usage

Running the MCP Server

1. Start the server:

python -m src.main

2. Complete the setup wizard.

3. Configure your LLM to use the MCP server

First-time Authentication

Custom Mode Setup

1. The server will ask you for your GHL Marketplace App Client ID and Secret
2. Install your App to generate an OAuth Token

Team Setup (Basic Machines)