# 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](https://www.hubspot.com/) 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](#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](#what-this-actually-does)
- [Why use an independent MCP server instead of the platform's own AI?](#why-use-an-independent-mcp-server-instead-of-the-platforms-own-ai)
- [Scope: this is intentionally narrow](#scope-this-is-intentionally-narrow)
- [Also from BackCrew](#also-from-backcrew)
- [Some words you'll see, explained](#some-words-youll-see-explained)
- [How this keeps you safe by default](#how-this-keeps-you-safe-by-default)
- [What it can look up (always safe)](#what-it-can-look-up-always-safe)
- [⚠️ What it can change (off by default)](#what-it-can-change-off-by-default)
- [How to set it up](#how-to-set-it-up)
- [Connecting it to Claude](#connecting-it-to-claude)
- [Testing it safely](#testing-it-safely)
- [For developers](#for-developers)
- [What's next](#whats-next)
- [Built by BackCrew](#built-by-backcrew)
- [License](#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](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](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](#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)

| What it covers | Examples |
| --- | --- |
| Contacts | Search and view contact records |
| Companies | Search and view company records |
| Deals | View deals and pipeline/stage configuration |
| Notes | View logged notes |
| Owners | View which team members can be assigned records |
| Associations | View which records are linked together |

11 look-up actions in total.

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

**`office-ops` level:**

| What it covers | Examples |
| --- | --- |
| Contacts, Companies, Deals | Create or update a record |
| Notes | Log a note and attach it to a record |
| Associations | Link or unlink two existing records |

**`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](https://nodejs.org) 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"):
   ```bash
   git clone https://github.com/jayson-svg/backcrew-mcp-hubspot.git .
   ```
4. Paste this and press enter. It installs the project's dependencies:
   ```bash
   npm install
   ```
5. Paste this and press enter. It builds the project:
   ```bash
   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.**
   ```bash
   pwd
   ```
7. Paste this and press enter. It creates your settings file from a template:
   ```bash
   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:

```json
{
  "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`](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](https://developers.hubspot.com/docs/api-reference/crm-contacts-v3)

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](ROADMAP.md).

## What's next

See [ROADMAP.md](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](mailto:jayson@backcrew.co)**

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

## License

[MIT](LICENSE)