Skip to main content
Glama
HubSpot CRM MCP Server

HubSpot CRM MCP Server

by SaraMarubel

HubSpot CRM MCP Server

An MCP server that connects Claude directly to a HubSpot CRM — search, create, and update contacts, deals, and support tickets, plus a cross-object account summary tool that stitches all three together into one brief. Built as a demonstration of the kind of integration work a client/solutions engineer actually ships: wiring a real customer's business system up to an AI assistant, with the auth, error handling, and test coverage a production integration needs — not a toy demo.

Why this exists

Enterprise customers who want to use Claude against their own tools need someone to build the connector. This repo is that connector for HubSpot: a small, focused MCP server exposing the CRM objects a sales/support team actually works with, so Claude can answer "what deals are in the proposal stage" or "summarize this account" against real data instead of a copy-pasted CRM export.

Related MCP server: HubSpot MCP Server

Tools

Tool

What it does

search_contacts

Free-text search across name, email, company

get_contact

Fetch one contact's full profile by ID

create_contact

Create a new contact

search_deals

Search deals, optionally filtered by pipeline stage

get_deal

Fetch one deal, including its associated contacts

create_deal

Create a deal, optionally associated with a contact

update_deal_stage

Move a deal to a new pipeline stage

search_tickets

Search support tickets, optionally filtered by priority

create_ticket

Create a support ticket, optionally associated with a contact

get_account_summary

The cross-object tool — one contact's profile + every deal + every ticket associated with them, in a single readable brief

get_account_summary is the one tool here that isn't a thin CRUD wrapper — it's the concrete reason to put an MCP server in front of a CRM instead of just using the CRM's own UI: assembling that view by hand normally means opening three separate tabs.

Setup

1. Install and build

npm install
npm run build

2. Get a HubSpot access token

Full walkthrough with troubleshooting: HubSpot setup guide. In short, as a HubSpot super admin:

  1. Go to Development → Legacy apps → Create legacy app → Private (HubSpot now files private apps under "legacy apps"; they remain supported).

  2. On the Scopes tab, grant read and write for each object:

    • crm.objects.contacts.read / .write

    • crm.objects.deals.read / .write

    • crm.objects.tickets.read / .write (the scope picker may label these simply tickets)

  3. Click Create app, open the Auth tab, then Show token and Copy.

A free HubSpot account works. A developer test account is optional; HubSpot's docs don't confirm legacy private apps are available inside them. New accounts hold very little data, so add a few test contacts, deals, and tickets before trying the tools.

Note: this server has been verified against a mocked fetch and against HubSpot's real API for authentication-error handling. A full end-to-end run against live CRM data with a valid token is still to do.

3. Provide the token

The server reads HUBSPOT_ACCESS_TOKEN from its environment and does not load .env on its own. Either set it in your MCP client config (step 4, recommended), export it in your shell, or run with Node's env-file flag (Node 20.6+):

export HUBSPOT_ACCESS_TOKEN="pat-your-token"
# or
node --env-file=.env dist/index.js

4. Point an MCP client at it

For Claude Desktop or Claude Code, add to your MCP config:

{
  "mcpServers": {
    "hubspot-crm": {
      "command": "node",
      "args": ["/absolute/path/to/hubspot-crm-mcp-server/dist/index.js"],
      "env": { "HUBSPOT_ACCESS_TOKEN": "your-token-here" }
    }
  }
}

Then ask Claude things like: "Search HubSpot for contacts at Acme" or "Give me an account summary for contact 12345".

5. Or test it standalone with the MCP Inspector (no Claude client needed):

npm run inspector

This opens a browser UI to call each tool directly and inspect the raw responses — the fastest way to verify the server works end-to-end against your own HubSpot data before wiring up a client.

Testing

npm test

The full suite (26 tests) runs against a mocked fetch — no live HubSpot token required, so CI can run on every push without secrets. Tests cover the HTTP client (auth headers, request shaping, error handling, 404-as-empty-list semantics for associations) and every tool's business logic (formatting, filtering, the multi-call get_account_summary fan-out, and graceful handling when an association write fails).

Architecture

src/
  hubspotClient.ts   Thin wrapper over HubSpot's REST API v3/v4 (plain fetch,
                      no HubSpot SDK dependency) — list/get/search/create/
                      update/associate, with an injectable fetch impl for tests
  format.ts           Shared response-formatting helpers
  tools/
    contacts.ts       Tool logic + MCP registration, contacts
    deals.ts          Tool logic + MCP registration, deals
    tickets.ts        Tool logic + MCP registration, tickets
    accountSummary.ts Cross-object account brief
  index.ts             Server entrypoint (stdio transport)
test/
  hubspotClient.test.ts   Unit tests for the HTTP client
  tools.test.ts           Unit tests for each tool's business logic
  mocks/hubspotMock.ts    Mocked-fetch test helpers

Each tool's business logic is a standalone exported function (searchContacts, createDeal, etc.) that registerXTools() wires into the MCP server — kept separate on purpose so the logic is directly unit-testable without spinning up an MCP transport.

Tech stack

TypeScript, the official @modelcontextprotocol/sdk, Zod for input validation/schema, Vitest for testing. No HubSpot SDK, no framework — plain fetch against documented REST endpoints, kept deliberately small and readable.

Limitations

  • create_ticket assumes the default HubSpot ticket pipeline (hs_pipeline: "0", first stage "1") — correct for a fresh portal, but a customized pipeline would need its own IDs looked up first.

  • Associations use HubSpot's v4 "default association" endpoint, which covers the common case (link a deal/ticket to a contact) but not custom association types.

  • No rate-limit backoff yet — HubSpot's API returns 429s under heavy use, which this surfaces as a normal HubSpotApiError rather than retrying.


Not affiliated with or endorsed by HubSpot. Built as a portfolio project demonstrating MCP server / API integration engineering.

Available Tools

10 tools
create_contactB

Create a new HubSpot contact. Email is required by HubSpot for deduplication; other fields are optional but recommended for a usable CRM record.

Inputs: email (required), phone, company, jobTitle, +2 more.

create_dealC

Create a new HubSpot deal, optionally associated with an existing contact. Amount is in the portal's default currency.

Inputs: dealName (required), amount, pipeline, contactId, +1 more.

create_ticketB

Create a new HubSpot support ticket, optionally associated with an existing contact.

Inputs: subject (required), content, priority, contactId.

get_account_summaryA

Build a single account brief for a contact: their profile, every deal associated with them (with stage and amount), and every support ticket associated with them (with priority). Use this instead of chaining get_contact + search_deals + search_tickets when you want the full picture in one call.

Inputs: contactId (required).

get_contactA

Fetch a single HubSpot contact by ID, including their core properties. Pair with get_account_summary for a fuller picture (deals + tickets included).

Inputs: contactId (required).

get_dealA

Fetch a single HubSpot deal by ID, including stage, amount, close date, and the contacts associated with it.

Inputs: dealId (required).

search_contactsA

Search HubSpot contacts by name, email, or company. Returns up to limit matches with their core properties. Use this before get_contact when you don't already have an ID.

Inputs: query (required), limit.

search_dealsB

Search HubSpot deals by name, optionally filtered to a specific pipeline stage. Useful for questions like 'what deals are in the proposal stage'.

Inputs: limit, query, dealStage.

search_ticketsA

Search HubSpot support tickets by subject text, optionally filtered by priority. Useful for 'what high-priority tickets are open' style questions.

Inputs: limit, query, priority.

update_deal_stageA

Move a deal to a new pipeline stage — the most common day-to-day CRM write action (e.g. advancing a deal from 'proposal' to 'closed won').

Inputs: dealId (required), dealStage (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 10 tools

    Disambiguation5/5

    Each tool maps to a distinct resource/action: search vs get vs create for contacts/deals/tickets, plus a dedicated deal stage updater and an account summary aggregator. Even get_contact and get_account_summary are clearly differentiated by the summary's broader scope.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun snake_case pattern: search_*, get_*, create_*, plus update_deal_stage and get_account_summary. No mixed conventions or vague verbs.

    Tool Count5/5

    10 tools is well-scoped for a HubSpot CRM server covering contacts, deals, and tickets. Each tool covers a meaningful operation without redundancy.

    Completeness3/5

    The surface covers search/get/create for contacts and deals, search/create for tickets, and deal stage updates, but lacks update/delete operations for contacts and tickets and a get_ticket by ID. These are notable gaps for a CRM lifecycle, though common workflows are still possible.

    Maintenance

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      Enables AI assistants to interact with a HubSpot CRM account via natural language, starting with read-only lookups and optionally enabling write operations like creating contacts, deals, and notes.
      11
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Exposes CRM tools from HubSpot to Claude and other agents, enabling pipeline analysis, deal risk detection, and automated follow-up drafting.
      704 npm
      MIT