HubSpot MCP Server

A HubSpot Model Context Protocol server for giving AI agents structured, on-demand access to HubSpot CRM and operating data.

This package is built on top of the original open-source work at lkm1developer/hubspot-mcp-server. The Boondock Labs version expands that foundation with broader HubSpot coverage, MCP API-key authentication support, token-health utilities, incremental fetch controls, and additional tools across HubSpot's CRM, Sales, Marketing, Service, CMS, Commerce, and Operations surfaces.

What This Server Does

The server exposes HubSpot as a set of typed MCP tools. Instead of loading an entire portal into an agent prompt, the agent can ask for the exact slice of context it needs:

• Recent or updated contacts, companies, deals, tickets, and orders
• Exact CRM records by ID
• Company activity and engagement timelines
• Tasks, notes, and engagement activity
• Pipelines, properties, users, lists, workflows, domains, and associations
• Marketing forms, form submissions, marketing emails, email events, and campaigns
• CMS content such as blog posts, landing pages, site pages, files, and HubDB tables
• Service content such as conversations and knowledge base articles
• Commerce objects such as products, quotes, orders, and line items
• Custom objects and general object search
• HubSpot OAuth token validation, token health, and refresh helpers

The result is a retrieval-first HubSpot interface for agents: discover the right tool, pull the relevant records, then continue reasoning with only the context that matters.

Why This Version Exists

The original project proved the basic idea: expose HubSpot CRM through MCP. This version has been extended for heavier agent workflows where HubSpot is not just a contact database, but an operating environment.

Important additions include:

• Much wider HubSpot object coverage beyond contacts and companies
• Limit-based retrieval on most list tools
• Incremental updatedAfter support on heavy CRM reads
• Cursor-based pagination helpers for HubSpot search and list APIs
• Rate limiting and 429 retry handling
• Token refresh and token health tools
• Support for direct HubSpot tokens or Morphed MCP API-key based auth
• Optional-scope handling for HubSpot features that may not be available in every portal
• More complete property sets for CRM records so agents can reason from richer context

Installation

npm install hubspot-mcp-server

For local development:

git clone https://github.com/lkm1developer/hubspot-mcp-server.git
cd hubspot-mcp-server
npm install
npm run build

If you are working from this expanded Boondock Labs package, use the package source you received or cloned, then run:

npm install
npm run build

Authentication

The server supports two authentication modes.

Direct HubSpot Token

Set one of the supported token environment variables:

HUBSPOT_ACCESS_TOKEN=your-hubspot-access-token

You can also pass the token at startup:

npm start -- --access-token=your-hubspot-access-token

The server also checks:

HUBSPOT_DEVELOPER_API_KEY=your-token
HUBSPOT_PERSONAL_ACCESS_KEY=your-token

Morphed MCP API Key

For Morphed-managed installs, the server can validate a Morphed MCP API key and retrieve the matching HubSpot OAuth token for that portal.

MORPHED_MCP_API_KEY=your-mcp-api-key
MORPHED_API_URL=https://morphed.io

Or pass the API key at startup:

npm start -- --api-key=your-mcp-api-key

Running The Server

Build first:

npm run build

Start over stdio:

npm start

Or:

node dist/index.js

The package also includes a stdio script:

npm run stdio

SSE Proxy Mode

For remote or browser-based MCP clients, you can run the server behind mcp-proxy-auth:

npx mcp-proxy-auth node dist/index.js

Set the auth verification endpoint:

AUTH_SERVER_URL=https://your-auth-server.com/verify

The SSE endpoint is then available through the proxy, with API-key verification handled before requests reach the MCP server.

Tool Groups

Core CRM

• hubspot_create_contact
• hubspot_create_company
• hubspot_create_note
• hubspot_get_active_companies
• hubspot_get_active_contacts
• hubspot_get_deals
• hubspot_get_tickets
• hubspot_get_orders
• hubspot_get_current_user
• hubspot_update_contact
• hubspot_update_company
• hubspot_get_contact_by_id
• hubspot_get_company_by_id
• hubspot_get_deal_by_id
• hubspot_get_ticket_by_id

Engagements And Activity

• hubspot_get_company_activity
• hubspot_get_recent_engagements
• hubspot_search_tasks
• hubspot_search_notes
• hubspot_get_engagement_associations
• hubspot_get_engagement_by_id

Sales Hub

• hubspot_get_pipelines
• hubspot_get_properties
• hubspot_get_quotes
• hubspot_get_users
• hubspot_get_lists
• hubspot_get_workflows

Marketing Hub

• hubspot_get_forms
• hubspot_get_form_submissions
• hubspot_get_marketing_emails
• hubspot_get_email_events
• hubspot_get_campaigns
• hubspot_get_analytics

Service Hub

• hubspot_get_conversations
• hubspot_get_knowledge_base

CMS Hub

• hubspot_get_blog_posts
• hubspot_get_landing_pages
• hubspot_get_site_pages
• hubspot_get_files
• hubspot_get_hubdb_tables
• hubspot_get_domains

Commerce Hub

• hubspot_get_products
• hubspot_get_line_items
• hubspot_get_orders
• hubspot_get_quotes

Operations And Enterprise

• hubspot_get_custom_objects
• hubspot_search_objects
• hubspot_get_associations

Token Utilities

• hubspot_refresh_token
• hubspot_validate_token
• hubspot_token_health

Context Strategy

The server is intentionally tool-first rather than prompt-dump-first.

Agents should not need to load every HubSpot record before doing useful work. They can start from the MCP tool list, choose the object family that matches the task, and request a bounded result set with limit, updatedAfter, or a specific record ID.

The heavier CRM reads use HubSpot sorting, cursor pagination, date filtering, and explicit property lists so the agent receives useful operational context without pulling the whole portal into memory at once.

That pattern makes the server useful for:

• CRM lookup and account research
• Workflow and list inspection
• Support and knowledge-base review
• Marketing and CMS context gathering
• Commerce object inspection
• Agentic HubSpot operations where the assistant needs just-in-time portal context

Extending The Server

To add a new HubSpot capability:

1. Add a method to HubSpotClient in src/hubspot-client.ts.
2. Register the MCP tool schema in setupToolHandlers inside src/index.ts.
3. Add the CallToolRequestSchema handler case in src/index.ts.
4. Rebuild with:

npm run build

Attribution

This package began from lkm1developer/hubspot-mcp-server. The current Boondock Labs package keeps that foundation and expands it into a broader HubSpot MCP surface for richer AI-agent workflows.

HubSpot is a trademark of HubSpot, Inc. This package is not an official HubSpot product.

License

MIT. See LICENSE.