Build an MCP Server on Top of the GoHighLevel API

mkdir ghl-mcp-server && cd ghl-mcp-server
npm init -y
npm install @modelcontextprotocol/sdk zod
# Optional but recommended:
npm install -D typescript @types/node tsx

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { z } from 'zod';

const GHL_TOKEN = process.env.GHL_TOKEN!;
const GHL_LOCATION_ID = process.env.GHL_LOCATION_ID!;
const GHL_BASE = 'https://services.leadconnectorhq.com';
const GHL_VERSION = '2021-07-28';

function ghlHeaders() {
  return {
    Authorization: `Bearer ${GHL_TOKEN}`,
    'Content-Type': 'application/json',
    Version: GHL_VERSION,
  };
}

const server = new McpServer({
  name: 'ghl-mcp-server',
  version: '1.0.0',
});

// Tool: search contacts
server.tool(
  'ghl_search_contact',
  'Search for a GoHighLevel contact by email or phone number.',
  {
    email: z.string().email().optional(),
    phone: z.string().optional(),
  },
  async ({ email, phone }) => {
    const params = new URLSearchParams({ locationId: GHL_LOCATION_ID });
    if (email) params.append('email', email);
    if (phone) params.append('phone', phone);

    const res = await fetch(`${GHL_BASE}/contacts/search?${params}`, {
      headers: ghlHeaders(),
    });
    const data = await res.json();
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(data.contacts ?? [], null, 2),
        },
      ],
    };
  }
);

// Tool: create contact
server.tool(
  'ghl_create_contact',
  'Create a new contact in GoHighLevel.',
  {
    email: z.string().email().optional(),
    phone: z.string().optional(),
    firstName: z.string().optional(),
    lastName: z.string().optional(),
    tags: z.array(z.string()).optional(),
  },
  async (fields) => {
    const res = await fetch(`${GHL_BASE}/contacts`, {
      method: 'POST',
      headers: ghlHeaders(),
      body: JSON.stringify({ locationId: GHL_LOCATION_ID, ...fields }),
    });
    const data = await res.json();
    return {
      content: [{ type: 'text', text: JSON.stringify(data.contact, null, 2) }],
    };
  }
);

// Tool: book appointment
server.tool(
  'ghl_book_appointment',
  'Book an appointment in a GoHighLevel calendar.',
  {
    calendarId: z.string(),
    contactId: z.string(),
    startTime: z.string().describe('ISO 8601 UTC datetime'),
    endTime: z.string().describe('ISO 8601 UTC datetime'),
    title: z.string().optional(),
  },
  async ({ calendarId, contactId, startTime, endTime, title }) => {
    const res = await fetch(`${GHL_BASE}/calendars/events/appointments`, {
      method: 'POST',
      headers: ghlHeaders(),
      body: JSON.stringify({
        calendarId,
        locationId: GHL_LOCATION_ID,
        contactId,
        startTime,
        endTime,
        title: title ?? 'Appointment',
        appointmentStatus: 'confirmed',
      }),
    });
    const data = await res.json();
    return {
      content: [{ type: 'text', text: JSON.stringify(data.appointment, null, 2) }],
    };
  }
);

// Start the server
const transport = new StdioServerTransport();
await server.connect(transport);

{
  "mcpServers": {
    "ghl": {
      "command": "node",
      "args": ["/absolute/path/to/ghl-mcp-server/src/index.js"],
      "env": {
        "GHL_TOKEN": "your_private_integration_token",
        "GHL_LOCATION_ID": "your_location_id"
      }
    }
  }
}

# Install the MCP inspector
npm install -g @modelcontextprotocol/inspector

# Run your server through the inspector
GHL_TOKEN=your_token GHL_LOCATION_ID=your_id \
  npx @modelcontextprotocol/inspector node src/index.js

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
import express from 'express';

// ... (same tool definitions as above) ...

const app = express();
app.use(express.json());

// Simple API key check - replace with real auth in production
app.use((req, res, next) => {
  if (req.headers['x-api-key'] !== process.env.MCP_API_KEY) {
    return res.status(401).json({ error: 'Unauthorized' });
  }
  next();
});

app.post('/mcp', async (req, res) => {
  const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
  await server.connect(transport);
  await transport.handleRequest(req, res, req.body);
});

app.listen(3000, () => console.log('GHL MCP server on port 3000'));

[
  {
    "name": "ghl_search_contact",
    "description": "Search for a GoHighLevel contact by email or phone.",
    "inputSchema": {
      "type": "object",
      "properties": {
        "email": { "type": "string" },
        "phone": { "type": "string" }
      }
    }
  },
  {
    "name": "ghl_create_contact",
    "description": "Create a new contact in GoHighLevel.",
    "inputSchema": {
      "type": "object",
      "properties": {
        "email": { "type": "string" },
        "phone": { "type": "string" },
        "firstName": { "type": "string" },
        "lastName": { "type": "string" },
        "tags": { "type": "array", "items": { "type": "string" } }
      }
    }
  },
  {
    "name": "ghl_book_appointment",
    "description": "Book an appointment in a GoHighLevel calendar.",
    "inputSchema": {
      "type": "object",
      "properties": {
        "calendarId": { "type": "string" },
        "contactId": { "type": "string" },
        "startTime": { "type": "string" },
        "endTime": { "type": "string" }
      },
      "required": ["calendarId", "contactId", "startTime", "endTime"]
    }
  }
]