BackCrew HubSpot MCP Server

Think of this like a brand-new employee on their first day, not a business partner. A new hire only does the exact tasks you've shown them, nothing more, until you decide they're ready for more responsibility.

It lets you connect an AI assistant like Claude or ChatGPT to your HubSpot account, so you can ask for things in plain English ("find this lead," "what deals are in the pipeline," "log this call as a note") instead of clicking through HubSpot yourself. On day one, it only knows how to look things up. You decide if and when to train it up to doing more.

HubSpot is a general sales/marketing CRM, not an FSM platform, but a lot of pest control businesses use it (or a tool like it) for lead intake and sales pipeline tracking alongside their actual field-service software. This repo is built to run alongside one of BackCrew's FSM servers in the same AI assistant.

Built by BackCrew, part of a series of free tools like this for pest control businesses.

Not a developer? That's fine. Everything up through "Testing it safely" is written for you, no coding background needed.

Contents

• What this actually does

• Why use an independent MCP server instead of the platform's own AI?

• Scope: this is intentionally narrow

• Also from BackCrew

• Some words you'll see, explained

• How this keeps you safe by default

• What it can look up (always safe)

• ⚠️ What it can change (off by default)

• How to set it up

• Connecting it to Claude

• Testing it safely

• For developers

• What's next

• Built by BackCrew

• License

What this actually does

Let's be upfront about what this is, because it's easy to oversell: this is not an all-knowing sales assistant that understands your pipeline and handles things for you. It's a specific, listed set of actions that an AI assistant is allowed to trigger when you ask for them in plain English. The AI doesn't have judgment about your business; it matches what you ask for to the closest action on its list and does exactly that, nothing more.

Why use an independent MCP server instead of the platform's own AI?

Software platforms are increasingly shipping their own built-in AI features. Worth knowing why you might still reach for this instead:

• No plan-tier gates. Native AI features are often locked to a platform's most expensive plan. This project just needs API access, which is usually available on lower tiers too.

• Cross-platform, not walled off. A platform's own AI only sees that platform's own data; it has no reason to work fluently with your FSM software, your accounting software, or your email, since those are somebody else's product. An MCP-connected assistant can have multiple servers attached at once (this one plus one of BackCrew's FSM servers), so it can work across your whole stack in one conversation.

• Your choice of AI, not theirs. You keep using whichever assistant you already trust (Claude, ChatGPT, whatever) instead of learning a new vendor-specific AI interface.

Scope: this is intentionally narrow

HubSpot's API covers a huge surface (marketing emails, workflows, forms, tickets, custom objects, and more). This repo covers exactly what's relevant to a pest control business managing leads and sales:

• Contacts: the people (leads, prospects, customers)

• Companies: the businesses those people belong to

• Deals: sales opportunities and where they sit in your pipeline

• Notes: logging a call, conversation, or other interaction on a record's timeline

• Owners: read-only, needed to assign records to a team member

• Associations: linking records together (a contact to a company, a note to a deal, etc.)

Not covered: marketing emails, workflows, forms, tickets, custom objects, and most of the rest of HubSpot's platform. See ROADMAP.md.

Also from BackCrew

This is one of several MCP connectors BackCrew builds, same idea, different software. We've also got FSM connectors like Housecall Pro, plus QuickBooks for the accounting side. Full list and what's live right now: see ROADMAP.md.

Beyond this repo: once a business gets comfortable with an AI assistant reading its data, there's often more it wants to do with it, like catching missed calls faster, processing invoices and paperwork automatically, following up on quotes without someone having to remember, reactivating customers who've gone quiet, or pulling reports without digging through the software. That's a separate, scoped conversation, not part of this free, open-source repo. Same contact as in Built by BackCrew below if it's something you want to explore.

Some words you'll see, explained

• API: a locked door into HubSpot's data that only software can open. This project is a key that opens that door.

• MCP: the standard way an AI assistant like Claude or ChatGPT is told what it's allowed to do.

• Server: a small program that sits between Claude and HubSpot, translating requests back and forth.

• Private App token: HubSpot's self-service equivalent of an API key. You generate it from your own HubSpot account settings, no separate developer account or OAuth flow needed for connecting to your own account.

• Association: HubSpot's term for a link between two records, e.g. a contact belonging to a company, or a note attached to a deal. Records aren't automatically connected; you (or this server) have to explicitly associate them.

• Terminal: a plain-text window where you type commands.

• Tool: one specific, individually named action the AI is allowed to take.

How this keeps you safe by default

• Out of the box, this server can only look things up. It ships in read-only mode.

• When you're ready for more, you choose a responsibility level:

  • readonly-owner: same as the default. Look-ups only.

  • office-ops: create/update contacts, companies, deals, and notes, and associate records together. No deletes.

  • admin: everything, including deletes.

• A typo can't accidentally hand out more trust than you intended. An invalid profile falls back to the safest option.

What it can look up (always safe)

11 look-up actions in total.

⚠️ What it can change (off by default)

office-ops level:

admin level only:

• Deleting a contact, company, deal, or note (HubSpot moves deleted records to a recycling bin recoverable for 90 days from the HubSpot UI; not undoable via this API, so treat it as effectively permanent from this tool's perspective)

How to set it up

No context-switching here: do these three steps in order, and you won't need to jump back and forth.

You'll need a computer with Node.js installed before you start.

Step 1: Make a folder for this on your computer

Open Finder (Mac) or File Explorer (Windows), go to your Desktop or Documents, and create a new folder. Give it a name you'll recognize later, like backcrew-mcp-hubspot.

That's it for now. Just know where this folder is. Everything else gets put inside it.

Step 2: Get a HubSpot Private App token

Do this now, before touching the terminal:

1. Log into your HubSpot account

2. Go to Settings → Integrations → Private Apps → Create a private app

3. Under Scopes, grant read/write access to the objects you want this server to touch (Contacts, Companies, Deals, Notes/Engagements, Owners)

4. Copy the generated access token into a temporary note somewhere; you'll paste it in during Step 3

Step 3: Install it

With your folder made and your token in hand, this is one continuous run: don't skip ahead or double back.

1. Open a terminal. On a Mac, press Cmd+Space, type "Terminal," and hit enter. On Windows, click the Start menu, type "PowerShell," and hit enter. Use PowerShell rather than Command Prompt: a couple of the commands below, like pwd, only work in PowerShell.

2. Type cd (with a space after it), then drag your Step 1 folder from Finder/File Explorer straight into the terminal window; it'll paste the folder's path in automatically. Press enter.

3. Paste this exact command and press enter. It downloads the project directly into the folder you made (the trailing . matters, it means "put it here, not in a new folder"):

   git clone https://github.com/jayson-svg/backcrew-mcp-hubspot.git .

4. Paste this and press enter. It installs the project's dependencies:

   npm install

5. Paste this and press enter. It builds the project:

   npm run build

6. Paste this and press enter. It prints the full folder path. Don't close this terminal window yet; you'll need this exact text in the next section.

   pwd

7. Paste this and press enter. It creates your settings file from a template:

   cp .env.example .env

8. Open that new .env file in a text editor. On a Mac, paste open -e .env into the terminal and press enter. On Windows, paste notepad .env and press enter.

9. Find the line that says HUBSPOT_ACCESS_TOKEN=. Paste in the token you copied in Step 2, right after the =, with no extra spaces or quotes.

10. Leave HS_MCP_MODE=read_only and HS_MCP_PROFILE=readonly-owner exactly as they are for now; that's the safe default. Save the file and close the editor.

Connecting it to Claude

This step comes last on purpose: it needs the exact folder location from Step 3, and now you have it.

Open Claude's settings file (for Claude Desktop, claude_desktop_config.json) and add:

{
  "mcpServers": {
    "hubspot": {
      "command": "node",
      "args": ["PASTE_YOUR_PWD_OUTPUT_HERE/dist/index.js"],
      "env": {
        "HUBSPOT_ACCESS_TOKEN": "your_token_here",
        "HS_MCP_MODE": "read_only",
        "HS_MCP_PROFILE": "readonly-owner"
      }
    }
  }
}

Replace PASTE_YOUR_PWD_OUTPUT_HERE with the exact text the pwd command printed back in Step 3 (keep the /dist/index.js part after it). If you're on Windows, swap any backslashes in that path for forward slashes (for example C:/Users/yourname/Desktop/... instead of C:\Users\yourname\Desktop\...), since the config file needs regular slashes.

Restart Claude. Also works with ChatGPT and other MCP-compatible AI tools. If you're also running one of BackCrew's FSM servers, add both to the same config.

Testing it safely

1. Start in read-only mode and stay there for a while.

2. When you turn on office-ops, test on a clearly fake contact first.

3. Never go straight to admin mode. Deletes aren't reliably undoable via the API.

4. Never share your Private App token: treat it like a password.

5. If something looks wrong, switch back to HS_MCP_MODE=read_only immediately.

For developers

Everything below this point assumes a coding background.

Tool reference

Run the server and call tools/list to see exact schemas: every tool's description includes the HubSpot API path it maps to and its access tier.

Why this repo uses a CRUD factory instead of hand-written tools per object

HubSpot's CRM v3 API is uniformly object-oriented: Contacts, Companies, Deals, and Notes (and every other CRM object) all share the same list/get/create/update/delete shape around a properties object and an optional associations array. Rather than hand-write near-identical code four times, this repo has one small factory, registerCrmObjectTools() in src/crud.ts, that generates the five tools for an object type from one config object (object type name, property fields, default tiers). Each generated tool is still a fully separate, individually named, individually gated MCP tool. Same rationale used elsewhere in this series for platforms with an equally uniform REST API.

Project layout

src/
  index.ts          Server entrypoint
  client.ts          Minimal fetch-based HubSpot API client (Bearer auth, error handling)
  toolkit.ts          Tier/profile-aware helper that wires a Zod input schema + handler into an MCP tool
  crud.ts             Factory that generates list/get/create/update/delete tools for uniform CRM objects
  tools/
    contacts.ts
    companies.ts
    deals.ts             (+ list_pipelines)
    notes.ts
    owners.ts              (read-only)
    associations.ts

The tier/profile system

Same pattern as the rest of this series: HS_MCP_MODE/HS_MCP_PROFILE gate what's registered at startup; read_only always wins; invalid profile falls back to the safest tier.

Notes on the HubSpot API

• Base URL: https://api.hubapi.com

• Auth header: Authorization: Bearer <private_app_token> (same header shape whether you're using a Private App token or an OAuth access token)

• CRM objects use properties (the actual field data) and associations (links to other records) as the two top-level request keys

• Pagination is cursor-based: pass after from a previous response's paging.next.after

• Association type IDs are numeric and HubSpot-assigned for default types (e.g. contact-to-company) or custom-assigned for user-defined labels; look them up via HubSpot's associations API guide or GET /crm/v4/associations/{fromObjectType}/{toObjectType}/labels

• Full reference: developers.hubspot.com

This server was built by reading HubSpot's public API documentation directly for Contacts, Companies, Deals, and Notes, with real field names and required-property rules taken from HubSpot's own docs.

This repo intentionally stops at honest API access. It does not include business-logic features; those live in BackCrew's managed offering, not in this public repo. See ROADMAP.md.

What's next

See ROADMAP.md for the rest of the planned series and the pattern this repo follows.

Built by BackCrew

This project is free and open for anyone to use, copy, or build on.

It's also a sample of the kind of work BackCrew does. If you want this expanded (tickets, workflows, custom properties) or connected alongside a specific FSM server for your business, that's exactly the kind of project we take on.

Want this done for you? Reach out: jayson@backcrew.co

No pressure either way, everything above works on its own, for free.

License

MIT