Model Context Protocol · v0.1.0

Connect Claude to your HubSpot CRM.

An MCP server that turns HubSpot contacts, deals, and support tickets into tools Claude can call directly — search, create, update, and one cross-object account brief. Built the way a client engineer ships a customer integration: authenticated, tested, and honest about its limits.

View source ↗ Setup guide

TypeScriptMCP SDKZodVitestMIT

claude › hubspot-crm

Illustrative output on sample data — format matches the real tool responses.

MCP tools

Unit tests · no live creds

HubSpot SDK dependencies

v3 / v4

HubSpot REST API

01 Overview

The connector enterprise customers keep asking for.

Teams that want Claude working against their own business systems need someone to build the bridge. This server is that bridge for HubSpot. It speaks the Model Context Protocol to Claude, and translates each tool call into a real, authenticated HubSpot API request.

Nothing here is simulated. Ask Claude to find a contact, move a deal to a new stage, open a support ticket, or summarize an account, and the change happens in the CRM — with the same auth, error handling, and association logic a production integration needs.

02 Tool surface

Ten tools across three CRM objects, plus one that isn't a thin wrapper.

Contacts

3 tools

search_contacts read
Free-text search across name, email, and company.
get_contact read
Fetch one contact's full profile by ID.
create_contact write
Create a new contact record.

Deals

4 tools

search_deals read
Search deals, optionally filtered by pipeline stage.
get_deal read
One deal plus its associated contacts.
create_deal write
Create a deal, optionally linked to a contact.
update_deal_stage write
Move a deal to a new pipeline stage.

Tickets

2 tools

search_tickets read
Search support tickets, optionally by priority.
create_ticket write
Open a ticket, optionally linked to a contact.

get_account_summary read

One contact's profile, every deal, and every ticket associated with them — fanned out in parallel and stitched into a single brief. The view a rep would otherwise assemble across three CRM tabs.

Cross-object

03 Architecture

Claude never touches HubSpot directly.

Every call is mediated, validated, and authenticated by the server, which is the only component that ever holds a credential.

Least privilege

The private-app token carries only contacts, deals, and tickets scopes, and lives in an environment variable — never hard-coded or logged.

Typed at the boundary

Every tool input is validated with Zod before a request is built, so malformed calls fail fast with a clear message.

Failures stay visible

A HubSpot auth or API error round-trips as a tool-level error Claude can read and react to, rather than crashing the server.

04 Demo

One call, one full account brief.

get_account_summary

The reason to put an MCP server in front of a CRM instead of just using its UI: contact, deals, and tickets fetched concurrently and returned as one readable brief Claude can reason over.

Illustrative output built from this project's own test fixtures.

get_account_summary { contactId: "12345" }

# Account Summary — Ada Lovelace Email: ada@acme.com | Company: Acme Corp | Title: VP Engineering Lifecycle stage: customer ## Deals (2) - Acme Platform Expansion — $48,000.00 — presentationscheduled - Acme Add-on Seats — $6,200.00 — closedwon Total deal value on record: $54,200.00 ## Support tickets (1) - SSO login redirect loop [HIGH]

05 Setup

From clone to Claude calling real HubSpot tools in five steps.

The short version. The full HubSpot walkthrough covers accounts, scopes, and troubleshooting.

Install and build

npm install
npm run build

Create a HubSpot private app

As a super admin: Development → Legacy apps → Create legacy app → Private, with read and write scopes for contacts, deals, and tickets. Step-by-step guide →

Copy the token

App → Auth tab → Show token. Pass it as HUBSPOT_ACCESS_TOKEN in your MCP config (next step) or export it in your shell.

Point Claude at it

Add this to your Claude Desktop or Claude Code MCP config:

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

Or test it standalone

Run npm run inspector to open the official MCP Inspector and call each tool directly — no Claude client required.

06 Stack

Small, readable, honest about its limits.

TypeScript @modelcontextprotocol/sdk Zod Vitest GitHub Actions

Every tool's business logic is a standalone exported function, separate from its MCP registration, so it can be unit-tested without spinning up a protocol transport. All 26 tests run against a mocked fetch — CI never needs a live HubSpot credential.

The server was also verified end-to-end with a real MCP client over stdio, including a genuine HubSpot authentication error round-tripping cleanly back through the protocol as a tool-level error instead of a crash.