HubSpot and Zendesk MCP Integration Guide

export HUBSPOT_ACCESS_TOKEN="pat-na1-your-hubspot-token"
export ZENDESK_SUBDOMAIN="companyhelp"
export ZENDESK_EMAIL="support-admin@example.com"
export ZENDESK_API_TOKEN="your-zendesk-api-token"

{
  "mcpServers": {
    "crm-ops": {
      "command": "node",
      "args": ["/opt/mcp-servers/crm/dist/index.js"],
      "env": {
        "HUBSPOT_ACCESS_TOKEN": "pat-na1-your-hubspot-token",
        "ZENDESK_SUBDOMAIN": "companyhelp",
        "ZENDESK_EMAIL": "support-admin@example.com",
        "ZENDESK_API_TOKEN": "your-zendesk-api-token"
      }
    }
  }
}

{
  "mcpServers": {
    "crm-ops": {
      "command": "node",
      "args": ["./dist/index.js"],
      "env": {
        "HUBSPOT_ACCESS_TOKEN": "pat-na1-your-hubspot-token",
        "ZENDESK_SUBDOMAIN": "companyhelp",
        "ZENDESK_EMAIL": "support-admin@example.com",
        "ZENDESK_API_TOKEN": "your-zendesk-api-token"
      }
    }
  }
}

[mcp_servers.crm_ops]
command = "node"
args = ["/opt/mcp-servers/crm/dist/index.js"]

[mcp_servers.crm_ops.env]
HUBSPOT_ACCESS_TOKEN = "pat-na1-your-hubspot-token"
ZENDESK_SUBDOMAIN = "companyhelp"
ZENDESK_EMAIL = "support-admin@example.com"
ZENDESK_API_TOKEN = "your-zendesk-api-token"

import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
import { Client as HubSpotClient } from '@hubspot/api-client';

const hubspot = new HubSpotClient({ accessToken: process.env.HUBSPOT_ACCESS_TOKEN });
const zendeskSubdomain = process.env.ZENDESK_SUBDOMAIN;
const zendeskEmail = process.env.ZENDESK_EMAIL;
const zendeskToken = process.env.ZENDESK_API_TOKEN;

const zendeskAuthHeader = 'Basic ' + Buffer.from(`${zendeskEmail}/token:${zendeskToken}`).toString('base64');

const server = new Server(
  { name: 'crm-hubspot-zendesk-mcp', version: '1.0.0' },
  { capabilities: { tools: {} } }
);

server.setRequestHandler(ListToolsRequestSchema, async () => {
  return {
    tools: [
      {
        name: 'get_hubspot_contact',
        description: 'Lookup customer details, company, and lifecycle stage by email address.',
        inputSchema: {
          type: 'object',
          properties: {
            email: { type: 'string', description: 'Customer email address' }
          },
          required: ['email']
        }
      },
      {
        name: 'get_zendesk_ticket',
        description: 'Retrieve ticket description, requester ID, and status by ticket ID.',
        inputSchema: {
          type: 'object',
          properties: {
            ticket_id: { type: 'number', description: 'Zendesk ticket ID number' }
          },
          required: ['ticket_id']
        }
      },
      {
        name: 'draft_zendesk_internal_note',
        description: 'Post a private internal note or draft response to a Zendesk ticket. Does not send to customer.',
        inputSchema: {
          type: 'object',
          properties: {
            ticket_id: { type: 'number', description: 'Zendesk ticket ID' },
            note_content: { type: 'string', description: 'Markdown formatted internal note content' }
          },
          required: ['ticket_id', 'note_content']
        }
      }
    ]
  };
});

server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const { name, arguments: args } = request.params;

  try {
    if (name === 'get_hubspot_contact') {
      const email = args?.email as string;
      const filter = { propertyName: 'email', operator: 'EQ' as any, value: email };
      const searchResponse = await hubspot.crm.contacts.searchApi.doSearch({
        filterGroups: [{ filters: [filter] }],
        properties: ['firstname', 'lastname', 'company', 'lifecyclestage', 'hs_lead_status'],
        limit: 1
      });

      if (!searchResponse.results.length) {
        return { content: [{ type: 'text', text: `No HubSpot contact found matching email: ${email}` }] };
      }

      return {
        content: [{ type: 'text', text: JSON.stringify(searchResponse.results[0].properties, null, 2) }]
      };
    }

    if (name === 'get_zendesk_ticket') {
      const ticketId = args?.ticket_id as number;
      const res = await fetch(`https://${zendeskSubdomain}.zendesk.com/api/v2/tickets/${ticketId}.json`, {
        headers: { Authorization: zendeskAuthHeader, 'Content-Type': 'application/json' }
      });

      if (!res.ok) {
        throw new Error(`Zendesk API error: ${res.status} ${res.statusText}`);
      }

      const data = await res.json();
      return {
        content: [{ type: 'text', text: JSON.stringify(data.ticket, null, 2) }]
      };
    }

    if (name === 'draft_zendesk_internal_note') {
      const ticketId = args?.ticket_id as number;
      const noteContent = args?.note_content as string;

      const payload = {
        ticket: {
          comment: {
            body: `[🤖 AI Diagnostic Draft - Internal Only]\n\n${noteContent}`,
            public: false // Enforce internal note only
          }
        }
      };

      const res = await fetch(`https://${zendeskSubdomain}.zendesk.com/api/v2/tickets/${ticketId}.json`, {
        method: 'PUT',
        headers: { Authorization: zendeskAuthHeader, 'Content-Type': 'application/json' },
        body: JSON.stringify(payload)
      });

      if (!res.ok) {
        throw new Error(`Failed to save draft note: ${res.statusText}`);
      }

      return {
        content: [{ type: 'text', text: `Successfully appended internal draft note to Zendesk ticket #${ticketId}.` }]
      };
    }

    throw new Error(`Tool ${name} is not recognized.`);
  } catch (err: any) {
    return {
      isError: true,
      content: [{ type: 'text', text: `CRM Operation Failed: ${err.message}` }]
    };
  }
});

async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
}

main().catch((err) => {
  process.stderr.write(`Fatal error: ${err.message}\n`);
  process.exit(1);
});

{
  "jsonrpc": "2.0",
  "id": "crm-op-101",
  "method": "tools/call",
  "params": {
    "name": "get_hubspot_contact",
    "arguments": {
      "email": "sarah.connor@cyberdyne.example"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": "crm-op-101",
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\n  \"firstname\": \"Sarah\",\n  \"lastname\": \"Connor\",\n  \"company\": \"Cyberdyne Systems\",\n  \"lifecyclestage\": \"customer\",\n  \"hs_lead_status\": \"ENTERPRISE_TIER_1\"\n}"
      }
    ]
  }
}

const authHeader = 'Basic ' + Buffer.from(`${email}/token:${apiToken}`).toString('base64');