Connect HubSpot to Claude Code

Search and update contacts, companies, deals, and notes in the CRM. Add Toolspoke to Claude Code once and it can use 15 HubSpot actions. Your HubSpot credential stays in Toolspoke, and you choose which actions Claude Code may call.

Set it up in Claude Code

Three steps, the first one once for every toolkit you will ever add.

  1. Add Toolspoke to Claude Code

    Run it in your project, then /mcp to sign in

    claude mcp add --transport http toolspoke https://toolspoke.com/mcp

    The sign-in opens in your browser, and Toolspoke asks you to approve it.

  2. Install HubSpot and connect it

    Add HubSpot to a project in your Toolspoke workspace.

    Private app access token. You provide it once, when you install the connector. Toolspoke encrypts it at rest and decrypts it only for the length of a single call, and the gateway attaches it to the outbound request itself, so it is never part of the arguments an agent sends.

    Private app access token
    HubSpot → Settings → Integrations → Private Apps → Create a private app. Grant it the CRM scopes the actions you plan to use need (crm.objects.contacts, crm.objects.companies, crm.objects.deals, crm.objects.notes, crm.schemas.*, plus crm.objects.owners.read), then copy the access token from the Auth tab. This is not an OAuth app and needs no developer account.
  3. Choose what Claude Code may do

    All 15 actions start on. Switch off any of the 5 actions that change something in HubSpot, and Claude Code gets a refusal if it tries.

What you can ask Claude Code for

A few of the HubSpot actions that only read, so they are safe to try first.

  • Search contact records
  • Fetch one contact record in full
  • Fetch one company record in full, by the record id search_companies returns
  • Search deal records

What Claude Code can do in HubSpot

10 actions read and 5 write.

Reads

  • Search contacts

    Search contact records. `query` matches HubSpot's default text properties (name, email, company, phone) the way the CRM search box does; `filters` is the precise form, one filter per property, and every filter in the list must match. Returns the properties you name plus each record's id, pass an id to get_contact for the whole record. Prefer this over get_contact whenever you are starting from a name, an email address or a company rather than from an id. Call list_properties for the property names this account actually has before filtering on anything beyond the standard ones.

  • Get contact

    Fetch one contact record in full. Takes the HubSpot record id that search_contacts returns; set id_property to "email" to look one up by email address instead, which saves a search when you already have the address. Ask for the properties you need. HubSpot returns a small default set otherwise, and use associations to see which companies, deals and tickets the contact is attached to.

  • Search companies

    Search company records, with the same body shape as search_contacts: `query` for free text over HubSpot's default text properties, `filters` for exact property conditions. Use it to turn a company name or domain into a record id before calling get_company, or before filtering deals by associations.company.

  • Get company

    Fetch one company record in full, by the record id search_companies returns. Set id_property to "domain" to look one up by web domain instead. Use associations to list the contacts and deals attached to it.

  • Search deals

    Search deal records. Beyond ordinary property filters this is the operation that answers pipeline questions: filter on dealstage, pipeline, closedate or amount, and sort by hs_lastmodifieddate to see what moved. HubSpot also accepts the association pseudo-properties here, {"propertyName": "associations.company", "operator": "EQ", "value": "<company id>"} returns that company's deals. Call list_pipelines first for the stage ids this account uses, since dealstage holds an internal id rather than the label shown in the UI.

  • Get deal

    Fetch one deal record in full, by the record id search_deals returns. Use associations to see which contacts and companies it is attached to; the returned dealstage is an internal stage id, which list_pipelines translates into a label.

  • List notes

    List the notes logged against one record, newest first, the written history of what people have said about a contact, company, deal or ticket. Give the record's own id and say which kind of record it is; the ids come from search_contacts, search_companies or search_deals. Returns the note bodies as HTML, since that is how HubSpot stores them.

  • List owners

    List the account's owners, the HubSpot users a record can be assigned to, with their ids, names and email addresses. Call it to turn a person's name into the hubspot_owner_id that create_deal, update_deal and create_note take. This is also the cheapest read in the connector, which is why it is the connection check.

  • List pipelines

    List the pipelines defined for an object type, each with its stages in display order. This is the translation table between what a person says and what the API takes: "Closed Won" is a label, closedwon is the stage id, and create_deal and update_deal only accept the id. Defaults to deals; pass tickets for the support pipelines.

  • List properties

    List every property defined on an object type, with its internal name, label, type and any dropdown options. Call this before filtering or writing anything non-standard: HubSpot accounts add custom properties freely, and a filter naming a property that does not exist comes back as an error rather than as an empty result. The internal name is what search_contacts, create_contact and update_deal take.

Writes

  • Create contact

    Create a contact. `properties` is a flat map of HubSpot property names to values, email is the one HubSpot treats as the unique key, so include it unless you have an external id scheme. HubSpot rejects a create whose email already exists; search_contacts first, and use update_contact when the record is already there. Call list_properties for the property names this account defines.

  • Update contact

    Change properties on an existing contact. Only the properties you send are touched; everything else is left alone, and sending an empty string clears a property. Get the record id from search_contacts or get_contact first. This cannot delete the record.

  • Create deal

    Create a deal. HubSpot needs dealname, and needs pipeline and dealstage to be internal ids rather than the labels shown in the UI, call list_pipelines first and copy the ids from there. hubspot_owner_id comes from list_owners. This creates the deal on its own; attaching it to a contact or company is a separate association HubSpot's UI usually does, and this connector does not expose the associations API.

  • Update deal

    Change properties on an existing deal, this is how a deal is moved to another stage, re-priced, or given a new close date. Only the properties you send are touched. dealstage must be an internal stage id from list_pipelines, not a label. This cannot delete the deal.

  • Create note

    Log a note on a CRM record. The note appears on that record's activity timeline for the account's own users; it is not sent to the contact and nobody outside the portal sees it, which is why this is a write rather than a destructive action. `body` is HTML, so line breaks want <br> rather than \n. `timestamp` is when the note should be dated, pass the current time in ISO 8601 unless you are back-dating something. Attach the note by giving the record's id and the HubSpot-defined association type for its object: 202 for a contact, 190 for a company, 214 for a deal, 228 for a ticket.

HubSpot in Claude Code: questions

Does Claude Code see my HubSpot credential?

No. The credential is stored encrypted in Toolspoke, and the gateway adds it to each call. Claude Code only ever talks to Toolspoke, and the dashboard shows the last four characters of the credential and nothing more.

Can I stop Claude Code from changing things in HubSpot?

Yes. Each of the 15 actions can be switched off for a project. Turn off the 5 that change something and Claude Code can only read.

Will 15 actions crowd Claude Code's context?

No. Toolspoke shows Claude Code five bridge tools, plus a guide where a toolkit has one, and Claude Code searches for the HubSpot action it needs when it needs it. Adding more toolkits does not add more tools to its list.

Can I add it once for every project?

Yes. Add --scope user to the command and Claude Code keeps Toolspoke in every project on this machine. Without it, the server is added to the project you ran the command in.

What does it cost?

Tool calls are free on every plan, and a HubSpot call does not run in a sandbox, so it bills nothing.

Try HubSpot in Claude Code

Free to start, and tool calls cost nothing on any plan.