open-ghl

This MCP server provides full integration with the GoHighLevel API v2, exposing both Tools (actions) and Resources (data browsing) that let your AI assistants manage contacts, conversations, forms, submissions, and more. After starting the server and completing the OAuth setup, you can issue commands through the Tools to create, update, delete, and search contacts; manage conversations and messages; handle opportunities and pipelines; and browse calendars, forms, and submissions. The Resources endpoints let you explore data in a read-only way, using URIs like contacts://{location_id} or conversations://{location_id} to navigate data without directly composing API requests. The server also supports automatic token refresh and multi-location handling for agency accounts.

Prerequisites:

• Python 3.12+
• uv package manager (or pip)
• A GoHighLevel Marketplace App with OAuth credentials

Installation steps:

1. Clone the repository git clone https://github.com/basicmachines-co/open-ghl-mcp.git cd open-ghl-mcp

2. Set up a Python virtual environment and install dependencies uv venv source .venv/bin/activate uv pip install -r requirements.txt

3. Prepare configuration (see mcp_config in this document or environment variables below)

4. Run the MCP server python -m src.main

5. Complete the initial setup wizard in the running server and configure your LLM to point at the MCP server URL.

Notes and tips:

• Ensure you have GoHighLevel Marketplace App credentials (Client ID and Secret) and set the OAuth redirect to http://localhost:8080/oauth/callback.
• The server handles automatic token refresh, but initial token exchange requires completing the OAuth flow via the server prompts.
• If using multi-location (agency) accounts, ensure your GoHighLevel credentials have access to the sub-accounts you intend to manage.
• The API offers both Tools (actions) and Resources (data browsing). Use Tools to perform actions like create_contact or get_conversations, and Resources to read data via URIs such as contacts://location_id.
• If you encounter environment-related issues, verify that Python 3.12+ is active in the virtual environment and that the .venv is activated before starting the server.