hubspot-connect-mcp

A read-only MCP server for the HubSpot CRM API that redacts personal data by default. Unlike a raw API passthrough, it:

• Redacts PII (names, emails, phones, addresses, engagement bodies, ticket subjects) before anything reaches the model, with an explicit opt-out.
• Trims HubSpot's verbose envelope (drops duplicate ids/timestamps, nulls, archived:false, paging URLs; dedupes associations), cutting response size ~30-50%.
• Covers the whole CRM with a handful of generic tools instead of one per object, keeping the tool surface small.

Install

Install from npm (Node ≥ 18.18):

npm install -g @hackspaces/hubspot-connect-mcp

This server is installed and run with node, not npx. Installing once and pointing node at the entrypoint is reproducible and offline-friendly; that's also how the MCP gateway consumes it.

Configure

Set your HubSpot private-app token and run the installed entrypoint over stdio:

HUBSPOT_ACCESS_TOKEN=pat-... \
  node "$(npm root -g)/@hackspaces/hubspot-connect-mcp/dist/index.js"

Register it with any MCP client by pointing at the installed file (resolve <entrypoint> once with the npm root -g path above):

{
  "mcpServers": {
    "hubspot": {
      "command": "node",
      "args": ["<entrypoint>/@hackspaces/hubspot-connect-mcp/dist/index.js"],
      "env": { "HUBSPOT_ACCESS_TOKEN": "pat-..." }
    }
  }
}

To run from source instead (development), see the Development section below.

Tools (read-only)

All generic over an objectType (contacts, companies, deals, tickets, notes, emails, and more, or a custom object type id):

| Tool | Purpose | |------|---------| | hubspot_list_objects | List records of a type (paginated) | | hubspot_get_object | Get one record by id | | hubspot_batch_read_objects | Read many records by id in one call | | hubspot_search_objects | Filter/search by property criteria plus full-text | | hubspot_count_objects | Count records matching a filter (returns the total) | | hubspot_get_associations | Records of another type linked to a record | | hubspot_list_association_types | Valid association labels between two types | | hubspot_list_properties | Available properties for a type (field discovery) | | hubspot_get_property | One field's definition and allowed values (resolves pipeline stages) | | hubspot_list_schemas | Custom object schemas (resolve custom type ids) |

Pass an explicit properties array on reads to keep responses small. Paginate with limit + the after cursor returned as next.

PII protection

Every tool response passes through a redaction layer before it reaches the model. Personal-data property keys (email, firstname, lastname, phone, address fields, ip_address, ticket subject, and engagement bodies such as hs_note_body / hs_email_text) are replaced with "[REDACTED]". Record ids and dashboard URLs are preserved so you can still pivot and open records.

Add extra property keys to redact (e.g. custom fields) in config/pii-redaction.json:

{ "additional_redact_keys": ["custom_ssn_field"] }

Opt-out: set HUBSPOT_MCP_ALLOW_PII=true to disable redaction entirely. A warning is printed to stderr at startup. Use only in trusted contexts.

Development

npm run dev        # run from source (stdio)
npm test           # run the unit tests
npm run typecheck  # type-check without emitting
npm run compare    # dev harness: measure the token win vs raw passthrough

Versioning

Single-sourced from the root VERSION file; scripts/sync-version.sh propagates it into package.json. See CHANGELOG.md.