HubSpot

Quick start

Always invoke through bash {baseDir}/scripts/invoke.sh — never call mcporter directly. The wrapper seeds the OAuth vault from the env-supplied tokens when needed, then calls mcporter.

bash {baseDir}/scripts/invoke.sh call maverick-hubspot.search_crm_objects objectType=contacts query="alice"
bash {baseDir}/scripts/invoke.sh call maverick-hubspot.get_pipeline_stages objectType=deals

For structured output (also surfaces transport errors as JSON envelopes — workaround for mcporter #153):

bash {baseDir}/scripts/invoke.sh call --output json maverick-hubspot.search_crm_objects objectType=contacts query="alice" | jq '.result.content'

Discover available tools and schemas:

bash {baseDir}/scripts/invoke.sh list maverick-hubspot --schema

Safety

Write operations (create_crm_object, update_crm_object, association changes, pipeline or stage changes, and activity logging) modify HubSpot CRM data visible to the connected portal. Confirm clear user intent before invoking write tools — search and read tools are safe to call freely while exploring. Read the current CRM object before updating properties or associations, and use internal property names such as firstname, email, dealstage, and hubspot_owner_id.

Authentication

Tokens are provisioned and rotated automatically. If a call returns HTTP 401 that doesn't recover within a few seconds, the OAuth grant has been revoked — re-authorize the integration to refresh credentials.

Data flow

Tool calls travel to HubSpot's hosted MCP service at https://mcp.hubspot.com over HTTPS, authenticated via OAuth. HubSpot sees the contact, company, deal, ticket, association, owner, and pipeline data referenced by each call. Use this skill for HubSpot-related work only; do not pass unrelated sensitive content through these tools.

Dependencies

• mcporter (github.com/steipete/mcporter) — MCP CLI used to invoke HubSpot's hosted MCP server. Auto-installed via npm install -g --ignore-scripts mcporter if missing on PATH (see install spec in frontmatter). The install spec uses unpinned mcporter (npm latest); operators with strict supply-chain controls should override the install to pin a specific version (e.g. mcporter@\x3Cversion>).
• jq (stedolan.github.io/jq) — JSON processor used by the vault initializer. System dependency; install via your OS package manager (apt install jq, brew install jq, etc.).
• flock (part of util-linux) — file locking used to serialize concurrent vault writes. Available by default on Linux; on macOS install via brew install flock.
• shasum (Perl, ships with Digest::SHA) — computes the SHA-256 hashes used to derive the mcporter vault key and the provisioned-token marker. Preinstalled on macOS and on Debian/Ubuntu (incl. the deployed cloudflare/sandbox Ubuntu 22.04 image); on minimal Linux images install perl-Digest-SHA. The script invokes shasum -a 256 rather than GNU sha256sum so it runs on stock macOS without coreutils.