CRMHubSpot

Install the HubSpot CLI and MCP server

Install the HubSpot CLI with npm, make a service key with the right scopes and sign in with it.

Install hubspot once on each computer where you or an agent use it. You need Node.js 22.16 or a later 22.x, or 24 or later. Node 23 is not supported.

npm install -g @wirecat/hubspot-cli
hubspot --version
hubspot doctor

doctor needs no network and opens no keyring. It shows the version, where settings live, the profiles that exist, and whether other users of the computer can read the settings.

Make a key

hubspot signs in with a key that belongs to one HubSpot account. A super admin, or a user with HubSpot's Developer tools access permission, makes it once (HubSpot's guide):

  1. Open Development, then Keys → Service keys in the left menu. Some accounts show it under Settings → Integrations → Service keys instead.
  2. Click Create service key and name it WireCat.
  3. Click Add new scope, tick each scope in the table below, and click Update. A key gets only the scopes its maker has.
  4. Click Create and confirm.
  5. Click the key's name, then Show and Copy. The key starts with pat-.

HubSpot stopped new private apps on 26 October 2026 (HubSpot's notice). An existing private app's access token still works: give the app the same scopes and copy the token from its Auth tab.

Give it these read scopes (HubSpot's list of scopes):

ScopeWhat it reads
crm.objects.contacts.read, crm.objects.companies.read, crm.objects.deals.readcontacts, companies and deals
crm.objects.owners.readthe owners deals are assigned to
crm.schemas.contacts.read, crm.schemas.companies.read, crm.schemas.deals.readthe properties of each
sales-email-readlogged e-mails. Notes, calls, meetings and tasks need no scope of their own: the contacts scope reads them
crm.objects.leads.readleads, on Sales Hub Professional or Enterprise only
ticketstickets, through api only

Writes are optional. Add these scopes only if hubspot may change records. Without them the key only reads:

ScopeWhat it changes
crm.objects.deals.writedeals: create, update, move, close and delete
crm.objects.contacts.writecontacts. Notes, calls, meetings and tasks written through api may ask for their own scope: the error names it
crm.objects.companies.writecompanies

A scope you leave out fails only the commands that need it, with the scope named in the error.

Sign in

Pick a profile name for the account, such as work, and paste the key when asked:

hubspot work session start

The key is read hidden, or from stdin (hubspot work session start < key.txt), never as an argument. hubspot asks HubSpot which account the key belongs to, and keeps the key with the account's id in the system keyring, or in a file only you can read with --credential-storage file. A second profile on the same account is refused.

hubspot work setup asks the same questions step by step. WireCat Desktop shows the same steps: it draws them from one JSON document the CLI prints, hubspot work setup show --json, in English, Spanish or Russian.

WCHUBSPOT_TOKEN in the environment takes the place of the saved key for every profile, as in CI. Set WCHUBSPOT_ACCOUNT beside it to the account's id: hubspot work session status --check with the token alone prints it as account. Every command that reaches HubSpot checks the id against the token first. A command that reads only the local copy needs one such command, such as sync, to have run before. api does not learn the account's time zone this way, so its spent daily allowance says to try again after a time in UTC, the earliest it can be back.

Next: use it.