HU
Developer Tools

HubSpot CRM Contacts & Companies MCP Server

Manage HubSpot CRM contacts and companies via MCP server to create, retrieve, and sync CRM data directly through Claude chat.

View on GitHub
Quick Install
npx -y @buryhuang/mcp-hubspot

Overview

This project implements an MCP (Model Context Protocol) server that connects Claude-style chat interfaces to HubSpot CRM contacts and companies. The server provides a small HTTP API that the MCP host (chat model) can call to search, create, update, and associate HubSpot CRM records directly from conversation context. That enables agents to read and manipulate CRM data without leaving the chat, and to keep the model’s context in sync with the customer’s real CRM state.

The server acts as an adapter: it authenticates to HubSpot using an API key or access token, translates MCP tool calls into HubSpot CRM v3 API requests, and exposes a manifest the model can use to discover available tools. This is useful for building conversational assistants that look up contact records, create new company records, and attach conversation summaries to customer timelines.

Features

  • Exposes an MCP manifest describing CRM-related tools for chat models
  • Create, retrieve, search, and update HubSpot Contacts
  • Create, retrieve, search, and update HubSpot Companies
  • Associate contacts and companies (link/unlink)
  • Translate simple JSON tool calls into HubSpot CRM v3 API requests
  • Lightweight adapter suitable for local development or deployment behind a secure endpoint

Installation / Configuration

Clone the repository and run the server. The example below assumes a Node.js environment (adjust commands if the repo uses another runtime).

  1. Clone the repo
git clone https://github.com/buryhuang/mcp-hubspot.git
cd mcp-hubspot
  1. Install dependencies and start (Node.js example)
# install dependencies
npm install

# start the server
npm start
  1. Environment variables

Create a .env file (or set environment variables in your deployment) with at least the following values:

# HubSpot API credentials
HUBSPOT_API_KEY=your_hubspot_api_key_or_token
# or if using OAuth access token:
HUBSPOT_ACCESS_TOKEN=your_oauth_access_token

# Server configuration
PORT=3000
BASE_URL=https://your-server.example.com   # used to construct manifest URLs
  1. Verify the MCP manifest

After starting, the server exposes a manifest the MCP host/model can consume. Example manifest endpoint (adjust path based on server logs):

GET https://your-server.example.com/.well-known/mcp.json

Available Resources

The server exposes a set of MCP-accessible tools that correspond to common HubSpot CRM operations. The exact HTTP endpoints and request/response formats are described in the manifest, but typical tools include:

  • listContacts — paginated list of contacts
  • getContact — fetch a contact by id or email
  • createContact — create a new contact with properties
  • updateContact — update properties of an existing contact
  • searchContacts — search contacts by query or property
  • listCompanies — paginated list of companies
  • getCompany — fetch a company by id or domain
  • createCompany — create a new company record
  • updateCompany — update a company’s properties
  • associateContactCompany — create/remove association between contact and company
  • syncConversation — attach a text note or timeline event to a contact or company

Example request bodies (tool-level) usually contain a JSON object such as:

{
  "tool": "createContact",
  "input": {
    "properties": {
      "email": "[email protected]",
      "firstname": "Jane",
      "lastname": "Doe",
      "phone": "555-1234"
    }
  }
}

Use Cases

  • Create a lead from chat

    • During a customer conversation, the model asks for missing info and then calls createContact with the collected properties to create the contact in HubSpot.

  • Lookup contact details to personalize responses

    • The model calls getContact or searchContacts by email to retrieve contact properties (company, lifecycle stage, recent activity) and uses that to tailor replies.

  • Attach conversation summaries to CRM records

    • After a support interaction, the model calls syncConversation to post a summary note to the contact’s timeline or to create a task for follow-up.

  • Associate leads with companies

    • When an account-level interaction discovers the customer’s company, the model calls createCompany (if needed) and associateContactCompany to link the contact and company records.

  • Bulk enrichment or reconciliation

    • Use listContacts and listCompanies to pull a dataset into a workflow steered by the model, then update matching records based on conversation-driven rules.

Notes and Next Steps

  • Security: Protect the server behind TLS and restrict access to MCP hosts authorized to call your tools. HubSpot tokens must be stored securely.
  • Manifest customization: The repository includes a manifest describing the available tools. Modify descriptions, input schemas, and URLs to reflect your deployment and policy.
  • Rate limits: HubSpot enforces API rate limits; design retries and backoff accordingly.
  • Logging and audit: Enable request logging and an audit trail for CRM changes initiated by chat to trace actions and handle errors.

Repository: https://github.com/buryhuang/mcp-hubspot

For developer questions, consult the repo issues or the manifest file to see exact tool names and expected input/output schemas.

Tags:developer-tools