HubSpot

@mindstone/mcp-server-hubspot

HubSpot MCP server for CRM operations (contacts, companies, deals, tickets, leads, tasks, notes, associations), properties and owners, marketing/lists, workflows, knowledge base lookups, and file operations.

*Multi-account HubSpot MCP with host-orchestrated OAuth, sandboxed file uploads, and source-attribution labels on every new record.*

Status

• Version: 0.4.1 · npm
• Auth: OAuth (host-orchestrated) (HUBSPOT_CLIENT_SECRET)
• Tools: 106 (crm-objects, associations, marketing, files, workflows, conversations)
• Surface: cloud-api
• Machine-readable: STATUS.json

Why this exists

HubSpot publishes an official HTTP MCP server (public beta announced early 2026), and several community HubSpot MCPs exist as well. When we built this connector we needed something different: a local-only server that runs on the user's machine, supports more than one HubSpot account at the same time, keeps each account's credentials in its own file, labels new records so people can tell what was created by an AI agent, and limits file uploads to a single workspace folder on disk. None of the existing options covered all of that, so we wrote our own and put it through our own security review.

Example interaction

"Find Acme Corp in HubSpot, log a note that we had a great call with their CTO, and follow up next Tuesday."

Tools the host calls:

1. search_hubspot_companies — looks up Acme Corp by name and returns its company ID.
2. create_hubspot_note — logs a note against the company record.
3. create_hubspot_task — schedules a follow-up task due next Tuesday, associated to the company.

Response (trimmed):

{

"company": { "id": "12345678901", "name": "Acme Corp" }, "note": { "id": "9876543210", "createdAt": "2026-05-19T14:02:11Z", "body": "Great call with CTO — discussed Q3 rollout." }, "task": { "id": "5566778899", "subject": "Follow up with Acme Corp", "dueDate": "2026-05-26T16:00:00Z" } }

Requirements

• Node.js 20+
• npm
• A host application that performs the HubSpot OAuth flow and writes per-account credentials to ${HUBSPOT_CONFIG_DIR}/credentials/*.token.json. This server reads those files; it does not run a local OAuth callback.
• A writable MCP_WORKSPACE_PATH directory if you intend to use the file-upload tools.

One-click install

After clicking the button, your host will prompt you to fill: HUBSPOT_CONFIG_DIR, HUBSPOT_ACCOUNT_EMAIL, HUBSPOT_CLIENT_ID, HUBSPOT_CLIENT_SECRET, HUBSPOT_SOURCE_LABEL, HUBSPOT_REQUEST_TIMEOUT_MS.

Manual config for Claude Desktop / Claude Code / Goose / Continue.dev (HubSpot)

{

"mcpServers": { "HubSpot": { "command": "npx", "args": [ "-y", "@mindstone/mcp-server-hubspot" ], "env": { "HUBSPOT_CONFIG_DIR": "", "HUBSPOT_ACCOUNT_EMAIL": "", "HUBSPOT_CLIENT_ID": "", "HUBSPOT_CLIENT_SECRET": "", "HUBSPOT_SOURCE_LABEL": "HubSpot MCP", "HUBSPOT_REQUEST_TIMEOUT_MS": "60000" } } } }

Quick Start

Install & build

cd <path-to-repo>/connectors/hubspot

npm install npm run build

npx (once published)

npx -y @mindstone/mcp-server-hubspot

Local

node dist/index.js

Configuration

This server is designed for host-orchestrated OAuth. It reads host-managed credentials from disk.

Required environment variables

• HUBSPOT_CONFIG_DIR — Config directory containing accounts.json and credentials/*.token.json.
• HUBSPOT_ACCOUNT_EMAIL — Account selector for this process (one MCP process per HubSpot account).
• MCP_WORKSPACE_PATH — Workspace root for local file tools (upload_hubspot_file, attach_file_to_record).

OAuth bridge variables (host-injected)

• HUBSPOT_CLIENT_ID
• HUBSPOT_CLIENT_SECRET
• HUBSPOT_SOURCE_LABEL (optional) — overrides the source attribution label used on new records (default: HubSpot MCP)

The server still boots without these values (unconfigured mode), but tools requiring authenticated HubSpot API access return structured auth_required responses.

Authentication flow

authenticate_hubspot_account returns a structured auth_required response:

{

"status": "auth_required", "user_action": { "id": "hubspot.connect_account" }, "agent_action": { "instruction": "Tell the user that HubSpot needs reauthentication. The host will open the OAuth flow in their browser; once complete, retry the original request." }, "setupToolName": "authenticate_hubspot_account" }

The host recognises this shape and drives the browser OAuth flow.

Host configuration examples

This server is designed for host-orchestrated OAuth: the host writes per-account credential files to disk and the server reads them. The examples below show the env shape — your host application is responsible for populating ${HUBSPOT_CONFIG_DIR}/credentials/*.token.json before tool calls succeed.

Claude Desktop / Cursor

{

"mcpServers": { "HubSpot": { "command": "npx", "args": ["-y", "@mindstone/mcp-server-hubspot"], "env": { "HUBSPOT_CONFIG_DIR": "/absolute/path/to/hubspot-config", "HUBSPOT_ACCOUNT_EMAIL": "you@example.com", "MCP_WORKSPACE_PATH": "/absolute/path/to/workspace", "HUBSPOT_CLIENT_ID": "your-hubspot-app-client-id", "HUBSPOT_CLIENT_SECRET": "your-hubspot-app-client-secret" } } } }

Until the host has written ${HUBSPOT_CONFIG_DIR}/credentials/you@example.com.token.json, tools that require authenticated HubSpot access return a structured auth_required response (see the Authentication flow above).

Local development (no npm publish needed)

{

"mcpServers": { "HubSpot": { "command": "node", "args": [" /connectors/hubspot/dist/index.js"], "env": { "HUBSPOT_CONFIG_DIR": "/absolute/path/to/hubspot-config", "HUBSPOT_ACCOUNT_EMAIL": "you@example.com", "MCP_WORKSPACE_PATH": "/absolute/path/to/workspace", "HUBSPOT_CLIENT_ID": "your-hubspot-app-client-id", "HUBSPOT_CLIENT_SECRET": "your-hubspot-app-client-secret" } } } }

Tools (106)

Account & authentication

• list_hubspot_accounts — List connected HubSpot accounts and their auth status.
• authenticate_hubspot_account — Start the OAuth flow to connect a HubSpot account.
• complete_hubspot_auth — Wait for the OAuth callback and persist credentials.
• remove_hubspot_account — Disconnect a HubSpot account and delete stored credentials (destructive).

Contacts

• search_hubspot_contacts — Search contacts by query or property filters.
• get_hubspot_contact — Get a single contact by ID.
• create_hubspot_contact — Create a contact (destructive).
• update_hubspot_contact — Update contact properties (destructive).
• delete_hubspot_contact — Permanently delete a contact (destructive).

Companies

• search_hubspot_companies — Search companies by query or property filters.
• get_hubspot_company — Get a single company by ID.
• create_hubspot_company — Create a company (destructive).
• update_hubspot_company — Update company properties (destructive).
• delete_hubspot_company — Permanently delete a company (destructive).

Deals

• search_hubspot_deals — Search deals by query or property filters. For full coverage, repeat with after from paging.next.after until no next cursor is returned.
• get_hubspot_deal — Get a single deal by ID.
• create_hubspot_deal — Create a deal; requires hubspot_owner_id (destructive).
• update_hubspot_deal — Update deal properties or move stage (destructive).
• delete_hubspot_deal — Permanently delete a deal (destructive).

Tickets

• search_hubspot_tickets — Search tickets with filters.
• get_hubspot_ticket — Get a single ticket by ID.
• create_hubspot_ticket — Create a support ticket (destructive).
• update_hubspot_ticket — Update ticket properties (destructive).
• delete_hubspot_ticket — Delete a ticket (destructive).

Leads (Sales Hub Pro/Enterprise)

• search_hubspot_leads — Search leads by query or property filters.
• get_hubspot_lead — Get a single lead by ID.
• create_hubspot_lead — Create a lead linked to a contact (destructive).
• update_hubspot_lead — Update lead properties (destructive).
• delete_hubspot_lead — Permanently delete a lead (destructive).

Tasks

• search_hubspot_tasks — Search tasks with filters.
• get_hubspot_task — Get a single task by ID.
• create_hubspot_task — Create a task (destructive).
• update_hubspot_task — Update task properties (destructive).
• delete_hubspot_task — Delete a task (destructive).

Notes

• search_hubspot_notes — Search notes by body text or property filters.
• get_hubspot_note — Get a single note by ID.
• create_hubspot_note — Create a note and optionally associate it with records (destructive).
• update_hubspot_note — Update a note's properties, e.g. edit its body (destructive).
• delete_hubspot_note — Permanently delete a note (destructive).

Custom objects

• search_hubspot_object — Search records of any object type, incl. tenant-defined custom objects (native full-text query).
• get_hubspot_object — Get a single record of any object type by ID.
• create_hubspot_object — Create a record of any object type (destructive). Custom objects need the crm.objects.custom.write scope.

Associations

• create_hubspot_association — Create an unlabeled association between two records (v3) (destructive).
• get_hubspot_associations — List associations of a given type for a record.
• delete_hubspot_association —