# BackCrew Housecall Pro 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. That's exactly how this works: it connects an AI assistant like Claude or ChatGPT to your [Housecall Pro](https://www.housecallpro.com/) account, so you can ask for things in plain English (things like "find this customer," "what's on the schedule Tuesday," "is this invoice paid") instead of clicking through the Housecall Pro website yourself. But out of the box, it can only look things up. Nothing else is switched on until you decide to switch it on.

Built by **[BackCrew](#built-by-backcrew)**, the first in a series of free tools like this for the software pest control companies use every day.

> Not a developer? That's fine. Everything up through "Testing it safely" is written for you: no coding background needed, and no computer jargon without an explanation first.

---

## 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)
- [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)
- [Things you can try asking](#things-you-can-try-asking)
- [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: it's **not** some all-knowing assistant that understands your business and runs things for you. It's a specific, named list of actions (things like "look up a customer," "schedule a job," "send an invoice") that an AI assistant is allowed to trigger when you ask in plain English. It doesn't have judgment about your business. It just matches what you ask for to the closest thing on its list and does exactly that. Nothing more.

That's still genuinely useful, though. Instead of this:

> *Open Housecall Pro → click Customers → search "Ruiz" → click into her profile → click Jobs tab → scroll to find this week...*

You just say:

> "Find the customer named Dana Ruiz and show me any jobs scheduled for her this week."

And it does the clicking for you: same actions you'd take yourself, just faster, and in plain English.

## 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 accounting software, another CRM, or your email, since those are somebody else's product. An MCP-connected assistant can have multiple servers attached at once (this one plus another BackCrew server covering a different part of your business), 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.

## Also from BackCrew

This is one of several MCP connectors BackCrew builds, same idea, different software. We've also got QuickBooks for the accounting side, plus CRM connectors like HubSpot and GoHighLevel for lead and marketing data. 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**: short for "Application Programming Interface." A locked door into Housecall Pro's data that only software (not a person clicking a mouse) can open. This project is a key that opens that door, so an AI can read and update your data directly instead of needing a screen to click through.
- **MCP**: short for "Model Context Protocol." The standard way an AI assistant like Claude or ChatGPT is told "here's exactly what you're allowed to do, and how to do it." This project speaks that standard, which is why it plugs into Claude (and similar tools) with no custom setup.
- **Server**: a small program that sits between Claude and Housecall Pro, translating requests back and forth. You start it once and leave it running; you never interact with it directly.
- **Repo** (short for "repository"): the folder of code for this whole project. "Clone the repo" just means "download a copy of this project."
- **Token** / **API key**: a long, private password-like code that proves a request is really coming from you. You'll generate one from your own Housecall Pro account (steps below) and never share it.
- **Terminal**: a plain-text window on your computer where you type commands instead of clicking buttons. We walk you through this step by step; you don't need to have used one before.
- **Tool**: one specific action the AI is allowed to take, like "look up a customer" or "send an invoice." Each one is listed and named individually: there's no hidden catch-all action.

## How this keeps you safe by default

The "new hire" comparison up top isn't just a nice way of putting it; it's the actual design:

- **Out of the box, this thing can only look things up.** It ships in **read-only mode**: nothing it does can create, change, delete, or send anything in your Housecall Pro account, because those actions aren't even switched on yet. There's no way to accidentally trigger a write action in the default setup, because the server doesn't even hand those tools to the AI.
- **When you're ready for more, you pick a responsibility level, not an all-or-nothing switch.** Turning on write access (`HCP_MCP_MODE=read_write`; see [setup](#how-to-set-it-up)) still means picking a **profile** that caps what's allowed:
  - `readonly-owner`: same as the default. Look-ups only. Day-one new hire.
  - `office-ops`: everyday front-desk work (book a job, update a customer, send an invoice). **No deleting, no voiding, no locking, no webhook/integration setup.** Those stay off even here.
  - `admin`: everything, including deletes, voids, locking jobs, and technical integration settings (webhooks). This is the only level where anything hard-to-reverse is possible.
- **A typo can't accidentally hand out more trust than you meant to.** If the profile setting is ever misspelled or invalid, it falls back to the safest option (read-only) instead of the most permissive one.

## What it can look up (always safe)

These only read data: nothing here can change a record, send anything to a customer, or cost you anything to run. This is what's available with zero extra setup:

| What it covers | Examples of what it can look up |
| --- | --- |
| Customers | Search, view profiles and service addresses |
| Jobs | View job details, line items, materials used, schedule |
| Appointments | View appointment times and status |
| Estimates | View estimates and their options |
| Invoices | View invoices, payment status |
| Employees | View technicians and office staff |
| Leads | View leads and where they came from |
| Materials & pricing | View your price book, materials, services |
| Company info & schedule | View company details, technician schedules, calendar |
| Tags | View existing tags |

30 look-up actions in total.

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

Everything below this line can create, edit, send, or delete something real in your Housecall Pro account. **None of it is available until you deliberately turn it on** (see [How this keeps you safe by default](#how-this-keeps-you-safe-by-default)). This section is here so you know exactly what you'd be turning on, not because any of it is active right now.

**`office-ops` level** (everyday front-desk actions):

| What it covers | Examples of what it can do |
| --- | --- |
| Customers | Add or update a customer, add a service address |
| Jobs | Create a job, schedule it, assign a technician, add line items/materials/notes, attach files |
| Appointments | Create, reschedule, confirm an appointment |
| Estimates | Create an estimate, add notes |
| Invoices | Generate an invoice from a job, send it to the customer |
| Leads | Create/update a lead, add notes |
| Materials & pricing | Add or update a material |
| Tags | Create or rename a tag |

**`admin` level only** (hard to reverse, or technical/integration-facing; kept separate from everyday office work on purpose):

- Deleting a job's line items, notes, schedule, or tags
- Locking a job so it can't be edited further
- Voiding an invoice
- Deleting a material, tag, or lead note
- Anything to do with **webhooks** (technical event notifications to other software). This entire area stays admin-only, including just viewing webhook settings, since it's an integration/engineering concern rather than everyday office work

## How to set it up

Do these three steps in order. Each one gathers everything you need before you move to the next, so you won't have to jump back and forth.

### Step 1: Make a folder for this on your computer

Before touching anything technical, just pick a spot and create an empty folder.

1. Open **Finder** (Mac) or **File Explorer** (Windows)
2. Go to your **Desktop** or **Documents**, anywhere easy to find again
3. Create a new folder and name it something like `backcrew-housecall-pro`

That's it. You now know exactly where this project is going to live. Keep this Finder/Explorer window handy; you'll need to find this folder again in Step 3.

### Step 2: Get your Housecall Pro key

Do this next, entirely inside Housecall Pro. No terminal yet.

1. Log into your Housecall Pro account
2. Click **App Store** in the left-hand menu
3. Click **API Key Management**
4. Click **Generate**
5. Copy the key it gives you, and paste it somewhere temporary (a Notes app, a blank email draft) so you don't lose it before Step 3

Housecall Pro's own instructions, if you want a second reference: [Housecall Pro API docs](https://docs.housecallpro.com).

You now have everything Housecall Pro needs to give you. Time to move to the terminal.

### Step 3: Install it

This is one continuous set of steps: do them in order, in the same terminal window.

1. **Open a terminal.** On a Mac, press `Cmd + Space`, type "Terminal," and press 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. **Move into the folder you made in Step 1.** Type `cd ` (with a space after it), then drag your `backcrew-housecall-pro` folder from Finder/Explorer straight into the terminal window (it'll fill in the full path for you), then press Enter.
3. **Download the project into that folder.** Paste this exactly and press Enter:
   ```bash
   git clone https://github.com/jayson-svg/backcrew-mcp-housecall-pro.git .
   ```
   (The period at the end matters: it tells it to download into the folder you're already in, instead of making a new one. If your computer asks to install "command line developer tools" the first time you use `git`, say yes; that's normal on a Mac that's never used git before.)
4. **Install what the project needs to run.** Paste and press Enter:
   ```bash
   npm install
   ```
5. **Get it ready to use.** Paste and press Enter:
   ```bash
   npm run build
   ```
6. **Get the folder's exact location; you'll need this in Step 4.** Paste and press Enter:
   ```bash
   pwd
   ```
   This prints out something like `/Users/yourname/Desktop/backcrew-housecall-pro`. Copy that whole line; you'll paste it into Claude's settings next.
7. **Create your settings file.** Paste and press Enter:
   ```bash
   cp .env.example .env
   ```
8. **Open that new file in a text editor.** On a Mac: type `open -e .env` and press Enter, and it'll open in TextEdit. On Windows: type `notepad .env` and press Enter.
9. **Paste in the key you copied in Step 2.** Find the line that says `HOUSECALL_PRO_API_KEY=` and paste your key right after the `=`, no spaces. Leave the other two lines (`HCP_MCP_MODE` and `HCP_MCP_PROFILE`) exactly as they are for now; more on those in [Testing it safely](#testing-it-safely).
10. **Save the file and close it.** (`Cmd+S` / `Ctrl+S`, then close the window.)

That's the whole install. Keep that `pwd` output from step 6 handy; the next section uses it.

## Connecting it to Claude

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

### Claude Desktop / Claude Code

1. Open Claude's settings file. For Claude Desktop, this is `claude_desktop_config.json`; Claude's own settings menu will show you where to find it.
2. Add this, replacing `PASTE_YOUR_PWD_OUTPUT_HERE` with what `pwd` printed in Step 3.6, and `paste_your_key_here` with your Housecall Pro key again. 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.

```json
{
  "mcpServers": {
    "housecall-pro": {
      "command": "node",
      "args": ["PASTE_YOUR_PWD_OUTPUT_HERE/dist/index.js"],
      "env": {
        "HOUSECALL_PRO_API_KEY": "paste_your_key_here",
        "HCP_MCP_MODE": "read_only",
        "HCP_MCP_PROFILE": "readonly-owner"
      }
    }
  }
}
```

3. Save the file and **restart Claude** completely (quit it, don't just close the window).

You should now see Housecall Pro show up as something Claude can use, with only the look-up actions available, by default. Nothing more to do; no need to go back to Housecall Pro or the terminal.

This also works with ChatGPT and other MCP-compatible AI tools (Cursor, Windsurf, and others). The setup step is basically the same.

## Things you can try asking

With the default (read-only) setup:

- "Show me all customers created in the last 30 days"
- "What jobs are scheduled for tomorrow?"
- "Which invoices are still unpaid from last month?"
- "Look up the customer at 918 Sycamore Court and show me her service history"

If you later turn on `office-ops`:

- "Set up a new account for Maria Alvarez at 918 Sycamore Court, Round Rock TX, and tag her as a referral from Dave"
- "Schedule a job for that customer next Tuesday at 9am and dispatch it to Mike"
- "Add a line item for a quarterly pest treatment at $89"
- "Tag that job as 'termite' and add a note that the crawl space is locked; call ahead"

## Testing it safely

If you do decide to turn on write access, a few habits save you a headache later:

1. **Start in read-only mode and just live with it for a while.** Get a feel for how the AI reads your requests before you ever let it change anything.
2. **When you do turn on `office-ops`, test on a clearly fake customer first.** Make a test customer named something obvious like "ZZZ Test Customer: Do Not Use" and try your first few write actions on that record, not a real one.
3. **Don't jump straight to `admin` mode.** Deletes, voids, and locks are hard or impossible to undo. `office-ops` covers real day-to-day work without touching any of that.
4. **Never share your API key.** Not in chat, not in a screenshot, not in a support ticket. Treat it like a password, because it functions like one.
5. **If anything looks off, flip back to `HCP_MCP_MODE=read_only` immediately.** That alone guarantees nothing further can change, no matter what the profile is set to.

## For developers

Everything below this point assumes a coding background.

### Tool reference

Run the server and call `tools/list` from any MCP client to see exact input/output schemas: every tool's description includes both the HTTP method/path it maps to and its access tier (e.g. `Maps to GET /jobs/{id}/line_items. [tier: readonly-owner]`). Each domain lives in its own file under [`src/tools/`](src/tools).

### The tier/profile system

Every call to `registerJsonTool(...)` declares a `tier`: `"readonly-owner" | "office-ops" | "admin"`. At startup, `src/toolkit.ts` reads `HCP_MCP_MODE` and `HCP_MCP_PROFILE` once, computes the maximum exposed tier, and any tool above that tier is never registered with the MCP server: it doesn't just get hidden from a menu, it's genuinely absent from `tools/list` and can't be called. `HCP_MCP_MODE=read_only` always wins over `HCP_MCP_PROFILE` regardless of what the profile is set to; only `read_write` lets the profile setting take effect. An unrecognized profile value falls back to `readonly-owner`, not the most permissive tier.

To add a new tool: pick the right tier when you call `registerJsonTool`, following the guidance in [What it can look up](#what-it-can-look-up-always-safe) / [What it can change](#what-it-can-change-off-by-default) above. No other file needs to change.

### Project layout

```
src/
  index.ts          Server entrypoint, registers every tool group and starts stdio transport
  client.ts          Minimal fetch-based Housecall Pro API client (auth headers, error handling)
  toolkit.ts          Tier/profile-aware helper that wires a Zod input schema + handler into an MCP tool
  tools/
    customers.ts
    jobs.ts
    employees.ts
    estimates.ts
    appointments.ts
    invoices.ts
    jobTypes.ts
    leads.ts
    materials.ts
    company.ts
    tags.ts
    webhooks.ts
```

### Notes on the Housecall Pro API

- Base URL: `https://api.housecallpro.com`
- Auth header: `Authorization: Token <api_key>` (API key) or `Authorization: Bearer <token>` (OAuth 2.0, integration partners only)
- Rate limits apply; a `429` response includes a `RateLimit-Reset` header with the epoch time the limit resets
- Full reference: [docs.housecallpro.com](https://docs.housecallpro.com)

This server was built by reading Housecall Pro's public API documentation directly, not by reverse-engineering another project's code. If you spot a field or endpoint that's drifted from what HCP actually returns, please open an issue or PR; the public docs are the source of truth.

This repo intentionally stops at honest API access. It does not include business-logic features (like a prioritized collections queue, capacity/route analysis, or automated escalation rules); those live in BackCrew's managed offering, built on top of this open layer, not in this public repo. See [ROADMAP.md](ROADMAP.md).

## What's next

This is the first of a planned series of tools like this, one per major piece of software pest control companies in the US and UK use to run their business. See [ROADMAP.md](ROADMAP.md) for what's coming next, and for the safety pattern (read-only default, tiered profiles) this repo established for the rest of the series.

## Built by BackCrew

This project is free and open for anyone to use, copy, or build on. That's the whole point.

It's also a sample of the kind of work **BackCrew** does: we build tools, automations, and AI setups like this one for pest control and field service businesses, including the business-logic layer (collections, capacity planning, escalation rules) that intentionally isn't part of this open repo. If you like what this does but don't want to set it up and maintain it yourself, or you want something built specifically for how your business runs, that's exactly the kind of project we take on.

**Want this set up 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)