SETUP_GUIDE.md•6.54 kB
# GoHighLevel MCP Server Setup Guide
## Overview
This guide provides exact step-by-step instructions to spin up the GoHighLevel MCP (Model Context Protocol) Server, which enables 269+ tools for integrating GoHighLevel CRM with Claude Desktop.
## Prerequisites Checklist
- [ ] Node.js 18+ installed (verify with `node --version`)
- [ ] GoHighLevel account with API access
- [ ] Claude Desktop installed
- [ ] Git installed (for cloning repository)
- [ ] Text editor for configuration files
## Step 1: Obtain GoHighLevel API Credentials (5 minutes)
### 1.1 Get Private Integrations API Key
1. Log into your GoHighLevel account
2. Navigate to: **Settings → Integrations → Private Integrations**
3. Click **"Create New Private Integration"**
4. Fill in:
- Name: `MCP Server Integration`
- Description: `Integration for Claude Desktop MCP`
5. Select ALL scopes (or specific ones based on needed tools)
6. Click **"Save Integration"**
7. **COPY AND SAVE** the generated Private API Key immediately
### 1.2 Get Location ID
1. Go to: **Settings → Company → Locations**
2. Select your location
3. Copy the **Location ID** from the URL or location details
## Step 2: Clone and Setup Repository (3 minutes)
```bash
# Clone the repository
git clone https://github.com/cpretzinger/GoHighLevel-MCP.git
# Navigate to project directory
cd GoHighLevel-MCP
# Install dependencies
npm install
```
## Step 3: Configure Environment Variables (2 minutes)
### 3.1 Create .env file
```bash
# Copy the example file
cp .env.example .env
# Edit the file with your credentials
nano .env # or use your preferred editor
```
### 3.2 Add your credentials to .env
```env
GHL_API_KEY=your_private_integrations_api_key_here
GHL_BASE_URL=https://services.leadconnectorhq.com
GHL_LOCATION_ID=your_location_id_here
NODE_ENV=production
PORT=8000
```
## Step 4: Build the Project (2 minutes)
```bash
# Build the TypeScript project
npm run build
# Verify build success
ls -la dist/
# Should see server.js and other compiled files
```
## Step 5: Configure Claude Desktop (5 minutes)
### 5.1 Locate Claude Desktop Config File
**macOS:**
```bash
open ~/Library/Application\ Support/Claude/
# Edit: claude_desktop_config.json
```
**Windows:**
```cmd
explorer %APPDATA%\Claude\
# Edit: claude_desktop_config.json
```
### 5.2 Add MCP Server Configuration
Replace the entire contents with (adjust paths):
```json
{
"mcpServers": {
"ghl-mcp": {
"command": "node",
"args": ["/Users/YourUsername/projects/GoHighLevel-MCP/dist/server.js"],
"env": {
"GHL_API_KEY": "your_private_api_key",
"GHL_BASE_URL": "https://services.leadconnectorhq.com",
"GHL_LOCATION_ID": "your_location_id"
}
}
}
}
```
**IMPORTANT:** Use absolute paths, not relative paths!
### 5.3 Restart Claude Desktop
1. Completely quit Claude Desktop (not just close window)
2. Reopen Claude Desktop
3. Look for the 🔨 tools icon in the bottom-right corner
## Step 6: Verify Installation (3 minutes)
### 6.1 Check MCP Connection in Claude
1. In Claude Desktop, look for the 🔨 icon
2. Click it to see available tools
3. You should see categories like:
- Contact Management
- Messaging & Conversations
- Calendar & Appointments
- etc.
### 6.2 Test Basic Commands
Try these commands in Claude:
- "List my GoHighLevel contacts"
- "Show me recent opportunities"
- "Check my calendar appointments"
## Alternative Deployment Options
### Option A: NPM Package Deployment (30 minutes)
```bash
# 1. Publish to NPM
npm login
npm version patch
npm publish --access public
# 2. Update Claude config to use NPM package:
{
"mcpServers": {
"ghl-mcp": {
"command": "npx",
"args": ["-y", "@yourusername/ghl-mcp-server"],
"env": {
"GHL_API_KEY": "your_api_key",
"GHL_BASE_URL": "https://services.leadconnectorhq.com",
"GHL_LOCATION_ID": "your_location_id"
}
}
}
}
```
### Option B: Cloud Deployment (45 minutes)
#### Vercel Deployment
```bash
# 1. Install Vercel CLI
npm i -g vercel
# 2. Deploy
vercel
# 3. Set environment variables in Vercel dashboard
# 4. Use the deployment URL in your applications
```
#### Docker Deployment
```bash
# 1. Build Docker image
docker build -t ghl-mcp-server .
# 2. Run container
docker run -p 8000:8000 \
-e GHL_API_KEY=your_key \
-e GHL_BASE_URL=https://services.leadconnectorhq.com \
-e GHL_LOCATION_ID=your_location_id \
ghl-mcp-server
```
## Troubleshooting
### Issue: Claude Desktop doesn't show tools
**Solution:**
1. Check config file JSON syntax (use jsonlint.com)
2. Ensure absolute paths are used
3. Verify Node.js is in PATH: `which node`
4. Check Claude logs: Help → Show Logs
### Issue: API Authentication Failed
**Solution:**
1. Confirm using Private Integrations API key (not regular API key)
2. Check API key has no extra spaces
3. Verify Location ID is correct
4. Test API key with curl:
```bash
curl -H "Authorization: Bearer your_api_key" \
https://services.leadconnectorhq.com/contacts/
```
### Issue: Build Fails
**Solution:**
```bash
# Clean rebuild
rm -rf node_modules package-lock.json dist/
npm install
npm run build
```
### Issue: Tools not working as expected
**Solution:**
1. Check specific tool permissions in GoHighLevel
2. Verify API scopes include required permissions
3. Check rate limits (60 requests/minute default)
4. Review server logs: `npm run start:stdio`
## Security Best Practices
1. **Never commit .env file** - it's in .gitignore
2. **Rotate API keys regularly** (every 90 days)
3. **Use environment variables** for all sensitive data
4. **Monitor API usage** in GoHighLevel dashboard
5. **Implement IP whitelisting** for production deployments
## Quick Reference
### Essential Commands
```bash
# Development
npm run dev # Start with auto-reload
npm run build # Build TypeScript
npm run test # Run tests
# Production
npm run start:stdio # For Claude Desktop
npm run start:http # For HTTP server
# Utilities
npm run lint # Check code style
npm run format # Auto-format code
```
### File Locations
- Config: `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
- Logs: Check Claude Desktop Help → Show Logs
- Build output: `./dist/`
- Environment: `./.env`
## Total Setup Time: ~15-20 minutes
Following these exact steps will have your GoHighLevel MCP Server running with Claude Desktop in under 20 minutes. For support, check the project's GitHub issues or GoHighLevel developer community.