Skip to main content
Glama
Sign In
hubspot-mcp-server

hubspot-mcp-server

by mantis-productions
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

hubspot-mcp-server

A Model Context Protocol (MCP) server for the HubSpot CRM API — works both locally via Claude Desktop (stdio) and remotely via claude.ai (HTTP + bearer token).

Tools

Domain

Tools

Contacts

hubspot_get_contact, hubspot_list_contacts, hubspot_create_contact, hubspot_update_contact, hubspot_delete_contact

Companies

hubspot_get_company, hubspot_list_companies, hubspot_create_company, hubspot_update_company, hubspot_delete_company

Deals

hubspot_get_deal, hubspot_list_deals, hubspot_create_deal, hubspot_update_deal, hubspot_delete_deal

Search & Assoc.

hubspot_search, hubspot_associate_records, hubspot_list_associations

Related MCP server: HubSpot MCP Server

Setup

1. Create a HubSpot Private App

  1. Go to HubSpot → Settings → Integrations → Private Apps

  2. Click Create a private app, then under Scopes add:

    • crm.objects.contacts.read + write

    • crm.objects.companies.read + write

    • crm.objects.deals.read + write

  3. Copy the generated Access Token

2. Install & Build

npm install
npm run build

Option A — Claude Desktop (local, stdio)

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

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

Restart Claude Desktop — the tools will appear automatically.

Option B — claude.ai browser (remote, HTTP via Render)

Step 1 — Deploy to Render

  1. Push this repo to GitHub

  2. Go to render.com → New → Web Service

  3. Connect your GitHub repo

  4. Render detects render.yaml automatically. Set these Environment Variables in the dashboard:

    Key

    Value

    HUBSPOT_ACCESS_TOKEN

    Your HubSpot private app token

    MCP_API_KEY

    A strong random secret you generate (e.g. openssl rand -hex 32)

    TRANSPORT

    http

  5. Deploy. Your URL will be: https://hubspot-mcp-server.onrender.com

Free tier note: Render's free tier spins down after 15 minutes of inactivity. The first request after spin-down takes ~30 seconds. Upgrade to Starter ($7/mo) to keep it always-on.

Step 2 — Connect in claude.ai

  1. Go to claude.ai → Settings → Integrations

  2. Click Add MCP Server

  3. Fill in:

    • URL: https://hubspot-mcp-server.onrender.com/mcp

    • Header name: Authorization

    • Header value: Bearer <your MCP_API_KEY>

  4. Click Connect — the 15 HubSpot tools will appear in your next conversation

Environment Variables

Variable

Required

Description

HUBSPOT_ACCESS_TOKEN

✅

HubSpot private app token

MCP_API_KEY

✅ (HTTP mode)

Bearer token that Claude.ai sends to authenticate

TRANSPORT

No

stdio (default) or http

PORT

No

HTTP port, default 3000 (Render sets this automatically)

Generate a secure MCP_API_KEY

openssl rand -hex 32

Copy the output into Render's environment variables and into the claude.ai header value field.

Local HTTP testing

HUBSPOT_ACCESS_TOKEN=pat-xxx MCP_API_KEY=mysecret TRANSPORT=http node dist/index.js

# Test auth
curl -X POST http://localhost:3000/mcp \
  -H "Authorization: Bearer mysecret" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

# Health check (no auth)
curl http://localhost:3000/health

Available Tools

18 tools
hubspot_associate_recordsAssociate HubSpot RecordsA
Idempotent

Create an association between two HubSpot CRM records (e.g. link a contact to a company, or a deal to a contact).

Args:

  • fromObjectType: "contacts" | "companies" | "deals"

  • fromObjectId: Source record ID

  • toObjectType: "contacts" | "companies" | "deals"

  • toObjectId: Target record ID

Supported pairs and their defaults:

  • contacts ↔ companies

  • deals ↔ contacts

  • deals ↔ companies

Returns: Confirmation of the association created

Inputs: fromObjectType (required), fromObjectId (required), toObjectType (required), toObjectId (required).

hubspot_create_companyCreate HubSpot CompanyA

Create a new company record in HubSpot CRM.

Args:

  • properties.name: Company name (recommended)

  • properties.domain: Website domain (e.g. acme.com)

  • properties.industry: Industry type

  • properties.city / state / country: Location

  • properties.numberofemployees: Employee count

  • properties.annualrevenue: Annual revenue in USD

Returns: Created company with its new record ID

Inputs: properties (required).

hubspot_create_contactCreate HubSpot ContactA

Create a new contact record in HubSpot CRM.

Args:

  • properties.email: Email address (required for unique identification)

  • properties.firstname / lastname: Name fields

  • properties.phone: Phone number

  • properties.company: Company name string

  • properties.jobtitle: Job title

  • properties.lifecyclestage: lead | customer | subscriber | etc.

  • associateWithCompanyId: Optionally link to a company record by ID

Returns: Created contact with its new record ID

Errors:

  • "CONTACT_EXISTS" if a contact with that email already exists

Inputs: properties (required), associateWithCompanyId.

hubspot_create_dealCreate HubSpot DealA

Create a new deal in HubSpot CRM.

Args:

  • properties.dealname: Deal name (required)

  • properties.amount: Deal value in USD

  • properties.dealstage: Pipeline stage slug (e.g. appointmentscheduled, closedwon, closedlost)

  • properties.pipeline: Pipeline ID (default: 'default')

  • properties.closedate: Expected close date in ISO 8601 (e.g. 2026-12-31)

  • properties.dealtype: newbusiness | existingbusiness

  • properties.hubspot_owner_id: HubSpot user ID for deal owner

  • associateWithContactId: Contact ID to associate

  • associateWithCompanyId: Company ID to associate

Returns: Created deal with new record ID

Inputs: properties (required), associateWithContactId, associateWithCompanyId.

hubspot_delete_companyDelete HubSpot CompanyA
DestructiveIdempotent

Archive (soft-delete) a company in HubSpot. Record moves to the recycle bin.

Args:

  • companyId (string): HubSpot company record ID

Returns: Confirmation message

Inputs: companyId (required).

hubspot_delete_contactDelete HubSpot ContactA
DestructiveIdempotent

Archive (soft-delete) a contact in HubSpot. The record moves to the recycle bin and can be restored within HubSpot.

Args:

  • contactId (string): HubSpot contact record ID

Returns: Confirmation message with deleted ID

Inputs: contactId (required).

hubspot_delete_dealDelete HubSpot DealA
DestructiveIdempotent

Archive (soft-delete) a deal in HubSpot. Record moves to the recycle bin and can be restored.

Args:

  • dealId (string): HubSpot deal record ID

Returns: Confirmation message

Inputs: dealId (required).

hubspot_get_companyGet HubSpot CompanyA
Read-onlyIdempotent

Retrieve a single HubSpot company record by ID.

Args:

  • companyId (string): HubSpot company record ID

  • additionalProperties (string[]): Optional extra properties to include

Returns: Company with id, name, domain, industry, city, state, country, phone, employees, annualRevenue, lifecycleStage

Inputs: companyId (required), additionalProperties.

hubspot_get_contactGet HubSpot ContactA
Read-onlyIdempotent

Retrieve a single HubSpot contact by their record ID.

Returns standard contact fields (name, email, phone, company, job title, lifecycle stage).

Args:

  • contactId (string): HubSpot contact record ID (numeric string)

  • additionalProperties (string[]): Optional extra property names to include

Returns: Contact object with id, firstName, lastName, email, phone, company, jobTitle, lifecycleStage

Errors:

  • "record not found" if the ID doesn't exist or the token lacks access

Inputs: contactId (required), additionalProperties.

hubspot_get_dealGet HubSpot DealA
Read-onlyIdempotent

Retrieve a single HubSpot deal record by ID.

Args:

  • dealId (string): HubSpot deal record ID

  • additionalProperties (string[]): Optional extra properties to include

Returns: Deal with id, dealName, amount, dealStage, pipeline, closeDate, dealType, description, ownerId

Inputs: dealId (required), additionalProperties.

hubspot_list_associationsList HubSpot Record AssociationsA
Read-onlyIdempotent

List all records of a given type associated with a source CRM record.

Args:

  • fromObjectType: "contacts" | "companies" | "deals"

  • fromObjectId: Source record ID

  • toObjectType: Object type to list associations for

Example: List all companies associated with contact 12345 fromObjectType="contacts", fromObjectId="12345", toObjectType="companies"

Returns: { associations: [{ id: string, type: string }], total: number }

Inputs: fromObjectType (required), fromObjectId (required), toObjectType (required).

hubspot_list_companiesList HubSpot CompaniesA
Read-onlyIdempotent

List company records from HubSpot CRM with pagination.

Args:

  • limit (number): Results per page, 1-100 (default 20)

  • after (string): Pagination cursor from a previous response

Returns: { companies: CompanyOutput[], hasMore: boolean, nextCursor?: string }

Inputs: limit, after.

hubspot_list_contactsList HubSpot ContactsA
Read-onlyIdempotent

List contacts from HubSpot CRM with pagination.

Args:

  • limit (number): Results per page, 1-100 (default 20)

  • after (string): Pagination cursor from a previous response

Returns: { contacts: ContactOutput[], hasMore: boolean, nextCursor?: string, total: number }

Inputs: limit, after.

hubspot_list_dealsList HubSpot DealsA
Read-onlyIdempotent

List deals from HubSpot CRM with pagination.

Args:

  • limit (number): Results per page, 1-100 (default 20)

  • after (string): Pagination cursor from a previous response

Returns: { deals: DealOutput[], hasMore: boolean, nextCursor?: string }

Inputs: limit, after.

hubspot_searchSearch HubSpot CRMA
Read-onlyIdempotent

Search contacts, companies, or deals using full-text query and/or property filters.

Args:

  • objectType: "contacts" | "companies" | "deals"

  • query (string): Full-text search string (e.g. "Acme Corp" or "john@example.com")

  • filters: Array of property filters: [{ propertyName: "email", operator: "EQ", value: "john@example.com" }] Operators: EQ, NEQ, CONTAINS_TOKEN, NOT_CONTAINS_TOKEN, GT, GTE, LT, LTE, HAS_PROPERTY, NOT_HAS_PROPERTY

  • properties (string[]): Property names to include in results

  • sortBy (string): Property name to sort by

  • sortDirection: "ASCENDING" | "DESCENDING"

  • limit (number): 1-100 results (default 20)

  • after (string): Pagination cursor

Returns: { total: number, results: HubSpotRecord[], hasMore: boolean, nextCursor?: string }

Examples:

  • Find a contact by email: objectType="contacts", filters=[{propertyName:"email",operator:"EQ",value:"jane@example.com"}]

  • Find open deals: objectType="deals", filters=[{propertyName:"dealstage",operator:"NEQ",value:"closedwon"}]

  • Find companies in a city: objectType="companies", filters=[{propertyName:"city",operator:"EQ",value:"Boston"}]

Inputs: objectType (required), query, filters, properties, +4 more.

hubspot_update_companyUpdate HubSpot CompanyA
Idempotent

Update properties on an existing HubSpot company. Only provided fields are changed.

Args:

  • companyId (string): HubSpot company record ID

  • properties: Any combination of company fields to update

Returns: Updated company record

Inputs: companyId (required), properties (required).

hubspot_update_contactUpdate HubSpot ContactA
Idempotent

Update properties on an existing HubSpot contact. Only provided fields are changed.

Args:

  • contactId (string): HubSpot contact record ID

  • properties: Any combination of contact fields to update

Returns: Updated contact record

Inputs: contactId (required), properties (required).

hubspot_update_dealUpdate HubSpot DealA
Idempotent

Update properties on an existing HubSpot deal. Only provided fields are changed.

Common use cases:

  • Move deal to next stage: update dealstage

  • Update close date or amount

  • Reassign deal owner via hubspot_owner_id

Args:

  • dealId (string): HubSpot deal record ID

  • properties: Any combination of deal fields to update

Returns: Updated deal record

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

Tool Schema Changelog

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

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    A4.2/5.0

    Scored across 18 tools

    Disambiguation5/5

    Each tool targets a distinct combination of CRM object (contact, company, deal) and action (create, get, update, delete, list), with separate tools for search and associations. There is no functional overlap, and an agent can clearly differentiate them.

    Naming Consistency5/5

    All tools follow the consistent pattern 'hubspot_<verb>_<object>' (e.g., hubspot_create_contact, hubspot_delete_company), with the exception of 'hubspot_search' and 'hubspot_list_associations' which still align with verb_object structure. Naming is uniform and predictable.

    Tool Count5/5

    With 18 tools covering CRUD for three objects (12 tools), list operations (3), search (1), and associations (2), the count is well-scoped for a CRM server. Each tool serves a distinct purpose without redundancy.

    Completeness4/5

    The tool set fully covers CRUD for contacts, companies, and deals, plus searching and listing. Associations are partially covered (create and list, but no dedicated delete association tool). This minor gap is the only missing piece, making the surface nearly complete.

    Maintenance

    ActivitySlowing
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers

    • HubSpot MCP Server

      baryhuang
      A
      license
      B
      quality
      D
      maintenance
      Enables AI models to interact with HubSpot CRM data and operations through a standardized interface, supporting contact and company management.
      16
      129
      MIT

    • HubSpot MCP Server

      dynamic
      A
      license
      Not graded
      quality
      Not graded
      maintenance
      Enables management of HubSpot CRM entities including contacts, companies, deals, and pipelines through natural language. It provides comprehensive tools for listing, searching, creating, and updating records with support for OAuth 2.0 authentication.
      MIT

    • HubSpot MCP Server

      adeel0x01
      A
      license
      B
      quality
      D
      maintenance
      Integrates with HubSpot CRM APIs via the Model Context Protocol, enabling management of contacts, companies, deals, tickets, notes, engagements, workflows, and more through natural language.
      82
      12 npm
      4
      MIT