Gohighlevel MCP

🚀 GoHighLevel MCP Server

This comprehensive MCP (Model Context Protocol) server connects the GoHighLevel community with AI automation. It provides access to all sub - account level GoHighLevel API endpoints, enabling seamless integration between GoHighLevel and AI systems.

🚀 Quick Start

This project is a foundational layer designed to connect the GoHighLevel community with AI automation through MCP. Before you start, here are some key points to note:

⚠️ Important Note

This project requires a PRIVATE INTEGRATIONS API key, not a regular API key!

✨ Features

• Foundation Layer: Offers access to ALL sub - account level GoHighLevel API endpoints via MCP.
• Community Starter: Built to accelerate the community's progress together.
• Open Architecture: The API client and types can be further modularized and segmented as needed.
• Educational Resource: Helps you learn how to integrate GoHighLevel with AI systems.

📦 Installation

🔑 GoHighLevel API Setup

This project requires a Private Integrations API key. Here's how to get it:

1. Login to your GoHighLevel account.
2. Navigate to Settings → Integrations → Private Integrations.
3. Create New Private Integration:
   • Name: MCP Server Integration (or your preferred name).
   • Webhook URL: Leave blank (not needed).
4. Select Required Scopes based on the tools you'll use:
   • ✅ contacts.readonly - View contacts.
   • ✅ contacts.write - Create/update contacts.
   • ✅ conversations.readonly - View conversations.
   • ✅ conversations.write - Send messages.
   • ✅ opportunities.readonly - View opportunities.
   • ✅ opportunities.write - Manage opportunities.
   • ✅ calendars.readonly - View calendars/appointments.
   • ✅ calendars.write - Create/manage appointments.
   • ✅ locations.readonly - View location data.
   • ✅ locations.write - Manage location settings.
   • ✅ workflows.readonly - View workflows.
   • ✅ campaigns.readonly - View campaigns.
   • ✅ blogs.readonly - View blog content.
   • ✅ blogs.write - Create/manage blog posts.
   • ✅ users.readonly - View user information.
   • ✅ custom_objects.readonly - View custom objects.
   • ✅ custom_objects.write - Manage custom objects.
   • ✅ invoices.readonly - View invoices.
   • ✅ invoices.write - Create/manage invoices.
   • ✅ payments.readonly - View payment data.
   • ✅ products.readonly - View products.
   • ✅ products.write - Manage products.
5. Save Integration and copy the generated Private API Key.
6. Copy your Location ID from Settings → Company → Locations.

💻 Usage Examples

📞 Customer Communication Workflow

"Search for contacts tagged 'VIP' who haven't been contacted in 30 days, then send them a personalized SMS about our new premium service offering"

💰 Sales Pipeline Management

"Create an opportunity for contact John Smith for our Premium Package worth $5000, add it to the 'Enterprise Sales' pipeline, and schedule a follow - up appointment for next Tuesday"

📊 Business Intelligence

"Get all invoices from the last quarter, analyze payment patterns, and create a report of our top - paying customers with their lifetime value"

🛒 E - commerce Operations

"List all products with low inventory, create a restock notification campaign, and send it to contacts tagged 'inventory - manager'"

📱 Social Media Automation

"Create a social media post announcing our Black Friday sale, schedule it for all connected platforms, and track engagement metrics"

🎯 Marketing Automation

"Find all contacts who opened our last email campaign but didn't purchase, add them to the 'warm - leads' workflow, and schedule a follow - up sequence"

📚 Documentation

This project comes with comprehensive documentation, including:

• 📖 Complete API Documentation
• 🎥 Video Tutorials
• 📋 Tool Reference Guide
• 🔧 Deployment Guides

🔧 Technical Details

System Requirements

Technology Stack

• Backend: Node.js + TypeScript
• HTTP Framework: Express.js 5.x
• MCP SDK: @modelcontextprotocol/sdk ^1.12.1
• HTTP Client: Axios ^1.9.0
• Testing: Jest with TypeScript support
• Build System: TypeScript compiler

API Integration

• GoHighLevel API: v2021 - 07 - 28 (Contacts), v2021 - 04 - 15 (Conversations)
• Authentication: Bearer token
• Rate Limiting: Respects GHL API limits
• Error Handling: Comprehensive error recovery

📄 License

This project is licensed under the ISC License - see the LICENSE file for details.

🔐 Security & Best Practices

Environment Security

• ✅ Never commit API keys to version control.
• ✅ Use environment variables for all sensitive data.
• ✅ Implement proper CORS policies.
• ✅ Regular API key rotation.
• ✅ Monitor API usage and rate limits.

Production Considerations

• ✅ Implement proper error handling and logging.
• ✅ Set up monitoring and alerting.
• ✅ Use HTTPS for all deployments.
• ✅ Implement request rate limiting.
• ✅ Regular security updates.

API Rate Limiting

• GoHighLevel API has rate limits.
• Implement exponential backoff.
• Cache frequently requested data.
• Use batch operations when available.

🚨 Troubleshooting Guide

Common Issues & Solutions

Build Failures:

# Clear cache and reinstall
rm -rf node_modules package-lock.json dist/
npm install
npm run build

API Connection Issues:

# Test API connectivity (use your Private Integrations API key)
curl -H "Authorization: Bearer YOUR_PRIVATE_INTEGRATIONS_API_KEY" \
     https://services.leadconnectorhq.com/locations/YOUR_LOCATION_ID

Common API Issues:

• ✅ Using Private Integrations API key (not regular API key).
• ✅ Required scopes enabled in Private Integration.
• ✅ Location ID matches your GHL account.
• ✅ Environment variables properly set.

Claude Desktop Integration:

1. Verify MCP configuration syntax.
2. Check file paths are absolute.
3. Ensure environment variables are set.
4. Restart Claude Desktop after changes.

Memory Issues:

# Increase Node.js memory limit
node --max-old-space-size=8192 dist/server.js

CORS Errors:

• Configure CORS_ORIGINS environment variable.
• Ensure proper HTTP headers.
• Check domain whitelist.

Performance Optimization

• Enable response caching for read operations.
• Use pagination for large data sets.
• Implement connection pooling.
• Monitor memory usage and optimize accordingly.

🆘 Community & Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• API Reference: GoHighLevel API Docs
• MCP Protocol: Model Context Protocol

🎉 Success Metrics

• ✅ 269 Operational Tools across 19 categories.
• ✅ Real - time GoHighLevel Integration with full API coverage.
• ✅ Production - Ready Deployment on multiple platforms.
• ✅ Enterprise - Grade Architecture with comprehensive error handling.
• ✅ Full TypeScript Support with complete type definitions.
• ✅ Extensive Test Coverage ensuring reliability.
• ✅ Multi - Platform Deployment (Vercel, Railway, Render, Docker).
• ✅ Claude Desktop Integration with MCP protocol compliance.
• ✅ Community - Driven Development with comprehensive documentation.

💝 Support This Project

This project represents hundreds of hours of development work to help the GoHighLevel community. If it's saving you time and helping your business, consider supporting its continued development:

• ⭐ Star this repo - Helps others discover the project.
• 🍕 Buy me a pizza - Donate via Stripe.
• 🐛 Report bugs - Help make it better for everyone.
• 💡 Suggest features - Share your ideas for improvements.
• 🤝 Contribute code - Pull requests are always welcome!

Contributors will be listed in the project, and significant contributions may get special recognition. This project is community - driven and community - supported.

Every contribution, big or small, helps keep this project alive and growing! 🚀