HubSpot MCP server

What it does

@hubspot/mcp-server is HubSpot's own package, released as a beta under its Early Adopter Program terms. It reads and writes CRM records (contacts, companies, deals, tickets and the other standard objects, plus custom objects), links records to each other, adds notes and tasks, and reads workflows. It authenticates with a private app access token, so it acts as that app across the whole account and not as any one user.

Tools

Version 0.4.0 lists 21 tools, and every one sets a read-only hint, which the last column follows. None of them delete or archive records.

Set it up

Both setups need a private app token. You must be a super admin. In HubSpot, go to Development, then Legacy apps (older accounts show Settings > Integrations > Private Apps). Click Create legacy app, pick Private, name it, and add scopes on the Scopes tab. After you create it, the token is on the Auth tab under Show token. It starts with pat-.

Scopes are where most of the safety comes from, because HubSpot refuses any call the token isn't scoped for, whatever your MCP client allows. HubSpot's own README suggests starting read-only. A reasonable read-only set:

• crm.objects.contacts.read, crm.objects.companies.read, crm.objects.deals.read, crm.objects.tickets.read
• crm.objects.owners.read, so records can be matched to people
• crm.schemas.contacts.read, crm.schemas.companies.read, crm.schemas.deals.read for the property tools
• crm.objects.custom.read and crm.schemas.custom.read if you use custom objects (Enterprise only)
• automation for the two workflow tools (Professional or Enterprise only)

Add a .write scope only for the object an agent has to change. crm.schemas.<object>.write is what lets hubspot-create-property and hubspot-update-property work, so leave it off unless you mean that. If a call fails on scopes, hubspot-get-user-details lists what the token actually has. The full list is in HubSpot's scopes reference.

Claude Code, directly:

claude mcp add hubspot -e PRIVATE_APP_ACCESS_TOKEN=pat-na1-your-token -- npx -y @hubspot/mcp-server@0.4.0

Cursor, directly, in ~/.cursor/mcp.json or .cursor/mcp.json:

{
  "mcpServers": {
    "hubspot": {
      "command": "npx",
      "args": ["-y", "@hubspot/mcp-server@0.4.0"],
      "env": {
        "PRIVATE_APP_ACCESS_TOKEN": "${env:HUBSPOT_PRIVATE_APP_TOKEN}"
      }
    }
  }
}

The client tutorials, How to add MCP servers to Claude Code and How to set up MCP servers in Cursor, explain config scopes and how to keep the token out of files you commit.

Through Statio: install HubSpot from the catalog, paste the token under the server's Credentials, and grant tools under Permissions. A new server has no grants, so nobody can call it until you add some. The desktop app then writes your client configs. The manual entry is the local proxy URL with the server name from your dashboard, http://127.0.0.1:7777/hubspot/mcp, added in Claude Code with claude mcp add --transport http hubspot <url> or as a "url" in Cursor. Tools missing after that? Start a fresh session, then work through How to debug an MCP server that won't connect.

What to hold back

Think about who reads the CRM after the agent does. Sales reps forecast from deal stages and amounts, marketing segments on lifecycle stage, and other integrations sync from the same fields. A wrong write spreads.

hubspot-batch-update-objects is the riskiest tool here. One call can set a property on 100 records. An agent asked to "close out the stale deals" can move a hundred of them to closed lost, reassign owners, or blank a field it misread. HubSpot keeps property history, so you can see the old values, but there's no tool here to put them back. A research or account-summary agent needs none of the seven write tools.

hubspot-create-property and hubspot-update-property change the account's data model, so they affect every record of that type and everyone using the account. Changing an enumeration's options or a property's field type can break forms, reports and workflows that depend on it. No agent doing day-to-day CRM work should hold them. Keep the schema write scopes off the token as well.

hubspot-batch-create-objects and hubspot-batch-create-associations cause quieter damage. A support agent that creates a contact for every email it reads fills the CRM with duplicates. A contact linked to the wrong company shows up in that company's timeline and in any report grouped by company.

hubspot-create-engagement is the write most support or sales-assist agents can reasonably have, since notes and tasks don't overwrite anything. Tasks do land in an owner's queue, so an agent that loops can bury a rep's task list. Grant it on its own, without the batch tools.

Records arrive in the agent's context from outside sources: form fills, imported lists, ticket text written by customers. Any of these can carry instructions aimed at the agent. Pairing the search tools with the batch writes is what turns that into changed data.

With Statio you grant each tool separately, so the same server can give one agent the reads and another the reads plus hubspot-create-engagement. MCP permissions covers how grants and denies combine.

Questions