GoHighLevel API v2와 원활한 통합을 제공하는 모델 Context Protocol (MCP) 서버. 이 서버는 포괄적인 접촉 관리로 시작된 GoHighLevel의 CRM 기능과 상호 작용하는 AI 조수가 가능합니다.

특징

• OAuth 2.0 인증**: 전체 OAuth 흐름 자동 토큰 관리
• A **Agency 또는 sub-account 범위 **: 기관 (회사) 토큰은 모든 관리 자동 대행사 → 위치 토큰 교환을 통해 하위 계정; 하위 계정 (Location) 토큰은 직접 사용되며 1개의 하위 계정으로 잠겨 있습니다.
• Curated 도메인: 연락처, 대화 및 메시징, 기회 및 파이프라인, 달력 & 약속, 모양, 주문 분야 & 가치, 노트 및 작업, 사용자 및 워크플로우 - API quirks를 처리하는 유형 도구
• ghl_list_endpoints] + ghl_request] 전체 GoHighLevel v2 API (Curated 도구를 넘어 긴 꼬리), 와 자동 토큰 라우팅, quirk 정상화 및 확인 destructive/high-impact 쓰기
• 자동 토큰 새로 고침**: 토큰 만료를 원활하게 처리
• 542️ ** 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)