@nubiia/mcp-hubspot

The most complete HubSpot MCP server for Claude.

A Model Context Protocol (MCP) server that gives Claude comprehensive, enterprise-grade access to HubSpot CRM — covering contacts, companies, deals, tickets, quotes, owners, pipelines, custom object schemas, engagements, workflows, and more, all through 54 battle-tested tools (70 with a developer key).

Built and maintained by Nubiia — automatización e integraciones con IA para negocios (MCP, HubSpot, Pipedrive, Holded y más). ¿Quieres algo así para tu empresa? Escríbenos en nubiia.es.

Features

• 54 Tools Across 10 Toolsets (+ 16 with developer key = 70 total) — complete coverage of the HubSpot CRM API surface

• Workflow Automation v4 BETA — create, update, monitor, and delete automation workflows

• Contact Enrollment — enroll and unenroll any CRM object in a workflow

• CRM Object CRUD — full create/read/update/archive for contacts, companies, deals, tickets, quotes, line_items, notes, calls, emails, meetings, and tasks

• Batch Operations — up to 100 objects per call for efficient bulk reads and writes

• Smart & Guided Search — filter groups with multiple operators and sorting, plus guided helpers (search_by_property, search_recent) so you don't hand-write filters

• Owner Resolution — translate hubspot_owner_id values into real users (name, email)

• Pipelines & Stages — translate dealstage / ticket stage IDs into readable stage labels

• Custom Object Schemas — define, inspect, update, and delete custom object types

• Engagement Logging — log a note/call/email/meeting/task and associate it to records in one call

• Deal & Quote Assembly — merge duplicate deals, assemble quotes from existing deals

• Association Management — link any two CRM objects with typed association labels

• Properties & Groups — discover, create, update, and archive property definitions and property groups

• Rate Limiting + Retry Logic — automatic backoff to protect your HubSpot API quota

• MCP Resources — three static reference resources (scope guide, object type catalog, conventions)

• MCP Prompts — five guided workflows to orchestrate multi-step CRM operations

• Toolset Filtering — enable only the domains you need via HUBSPOT_TOOLSETS

• Full TypeScript — strict types, Zod validation, and comprehensive TSDoc

Related MCP server: hubspot-mcp

Tool Categories

¹ The v3 legacy tools (hubspot_workflows_v3_list, hubspot_workflows_v3_get) belong to the automation toolset — activate them with HUBSPOT_TOOLSETS=automation.

² Actions tools use developer API key auth (hapikey) instead of a Private App access token and are only registered when HUBSPOT_DEVELOPER_API_KEY is present. See Actions Toolset below.

Installation

Global install

npm install -g @nubiia/mcp-hubspot

Via npx (no install needed)

npx @nubiia/mcp-hubspot

Configuration

Prerequisites

You need a HubSpot Private App to obtain an access token:

1. Log in to HubSpot and go to Settings → Integrations → Private Apps

2. Click Create a Private App

3. Give it a name and select the required scopes (see table below)

4. Click Create app and copy the generated access token (pat-na1-...)

Claude Desktop Setup

Add the server to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "hubspot": {
      "command": "npx",
      "args": ["-y", "@nubiia/mcp-hubspot"],
      "env": {
        "HUBSPOT_ACCESS_TOKEN": "pat-na1-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
      }
    }
  }
}

Environment Variables

Required Scopes

Grant only the scopes your use-case needs:

Advanced Configuration Examples

Enable only sales and properties toolsets:

{
  "mcpServers": {
    "hubspot": {
      "command": "npx",
      "args": ["-y", "@nubiia/mcp-hubspot"],
      "env": {
        "HUBSPOT_ACCESS_TOKEN": "pat-na1-...",
        "HUBSPOT_TOOLSETS": "sales,properties"
      }
    }
  }
}

Enable debug logging for troubleshooting:

{
  "env": {
    "HUBSPOT_ACCESS_TOKEN": "pat-na1-...",
    "LOG_LEVEL": "debug"
  }
}

Usage Examples

Create a deal and attach products

"Create a deal named 'Acme Corp - Enterprise Plan' closing on March 31st, add a line item for the Enterprise annual plan at $24,000, and associate it with the contact john.doe@acme.com."

Claude will:

1. Search for the contact by email using hubspot_crm_search

2. Create the deal with hubspot_crm_create (objectType: deals)

3. Create the line item with hubspot_crm_create (objectType: lineItems)

4. Link them with hubspot_associations_create

5. Associate the contact with hubspot_associations_create

Find all deals closing this month above $10k

"Search for all open deals with a close date in the current month and amount greater than $10,000. Sort by amount descending."

Claude will:

1. Use hubspot_crm_search with filterGroups combining closedate BETWEEN and amount GT operators

2. Set sorts to [{ propertyName: "amount", direction: "DESCENDING" }]

3. Paginate through results using the after cursor if there are more than one page

Enroll a contact who just filled a form in the onboarding workflow

"The contact with ID 98765 just submitted the trial sign-up form. Enroll them in the onboarding workflow."

Claude will:

1. Use hubspot_workflows_list to find the onboarding workflow (filtering by objectTypeId for contacts)

2. Verify the contact exists with hubspot_crm_get

3. Enroll with hubspot_enrollment_enroll

4. Confirm enrollment with hubspot_enrollment_get_enrollments

Workflows v4 BETA

The workflows toolset uses HubSpot's Workflows v4 API, which is currently in BETA:

• Breaking changes may occur without notice

• Access requires explicit approval from HubSpot — contact HubSpot support if you receive 403 errors

• The following tools are included in the workflows toolset: hubspot_workflows_list, hubspot_workflows_get, hubspot_workflows_create, hubspot_workflows_update, hubspot_workflows_delete, hubspot_workflows_batch_read, hubspot_workflows_email_campaigns, hubspot_workflows_performance, hubspot_workflows_id_mappings

For stable, read-only access to existing workflows, use the legacy v3 tools included in the automation toolset:

• hubspot_workflows_v3_list — list all workflows

• hubspot_workflows_v3_get — get a specific workflow by ID

Actions Toolset (Phase 7)

The actions toolset exposes 16 tools for managing Custom Workflow Action definitions — the reusable action types that developers can publish to the HubSpot Workflows editor.

Required environment variables

Activation

Actions tools are only registered when HUBSPOT_DEVELOPER_API_KEY is present. They do not appear in the tool list when only HUBSPOT_ACCESS_TOKEN is configured. You can also explicitly enable them via HUBSPOT_TOOLSETS=actions (still requires the developer key).

Authentication

All 16 hubspot_actions_* tools authenticate via hapikey (developer API key appended to the query string), not the Private App bearer token used by the other 37 tools.

Tools

Claude Desktop configuration example

{
  "mcpServers": {
    "hubspot": {
      "command": "npx",
      "args": ["-y", "@nubiia/mcp-hubspot"],
      "env": {
        "HUBSPOT_ACCESS_TOKEN": "pat-na1-...",
        "HUBSPOT_DEVELOPER_API_KEY": "your-developer-api-key",
        "HUBSPOT_APP_ID": "123456"
      }
    }
  }
}

Known Limitations

• Search latency: Records created or updated via the API may take 1–5 minutes to appear in hubspot_crm_search results due to HubSpot's indexing pipeline

• Batch cap: All hubspot_crm_batch_* tools enforce a hard limit of 100 objects per call; split larger sets across multiple calls

• Workflows v4 API: Subject to breaking changes while in BETA; HubSpot support approval required for access

• Quote assembly: hubspot_quotes_assemble requires the deal to have at least one associated line item; the call will fail otherwise

MCP Resources

Three static reference resources are available to LLM clients:

MCP Prompts

Five guided workflow prompts help orchestrate multi-step operations:

Contributing

See CONTRIBUTING.md for development setup, code style guidelines, testing requirements, and how to add new tools.

Security

See SECURITY.md for the vulnerability reporting policy and security best practices.

About Nubiia

This MCP server is built and maintained by Nubiia.

Nubiia ayuda a empresas a automatizar procesos e integrar sus herramientas con IA: servidores MCP a medida, integraciones con CRMs y ERPs (HubSpot, Pipedrive, Holded), y agentes que conectan tus datos de negocio con asistentes como Claude. Este @nubiia/mcp-hubspot es un ejemplo open source de lo que hacemos.

👉 ¿Quieres una integración o automatización con IA para tu negocio? nubiia.es · ✉️ hola@nubiia.es

Author

Built by Nubiia — nubiia.es · hola@nubiia.es

Maintainer: Samuel Fraga — GitHub

Links

• Nubiia — AI automation & integrations

• npm package

• GitHub repository

• Model Context Protocol

License

MIT — Copyright (c) 2025 Samuel Fraga