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 doctordoctor 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):
- Open Development, then Keys → Service keys in the left menu. Some accounts show it under Settings → Integrations → Service keys instead.
- Click Create service key and name it WireCat.
- Click Add new scope, tick each scope in the table below, and click Update. A key gets only the scopes its maker has.
- Click Create and confirm.
- 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):
| Scope | What it reads |
|---|---|
crm.objects.contacts.read, crm.objects.companies.read, crm.objects.deals.read | contacts, companies and deals |
crm.objects.owners.read | the owners deals are assigned to |
crm.schemas.contacts.read, crm.schemas.companies.read, crm.schemas.deals.read | the properties of each |
sales-email-read | logged e-mails. Notes, calls, meetings and tasks need no scope of their own: the contacts scope reads them |
crm.objects.leads.read | leads, on Sales Hub Professional or Enterprise only |
tickets | tickets, through api only |
Writes are optional. Add these scopes only if hubspot may change records. Without them the key only reads:
| Scope | What it changes |
|---|---|
crm.objects.deals.write | deals: create, update, move, close and delete |
crm.objects.contacts.write | contacts. Notes, calls, meetings and tasks written through api may ask for their own scope: the error names it |
crm.objects.companies.write | companies |
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 startThe 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.