BackCrew Housecall Pro MCP Server

Think of this project as an employee badge, not a master key.

It lets you connect an AI assistant like Claude to your Housecall Pro account, so you can ask for things in plain English — "find this customer," "what's on the schedule Tuesday," "is this invoice paid" — instead of clicking through the Housecall Pro website yourself. But like a real employee badge, it only opens the specific doors you hand it a key for. Out of the box, every door is locked to "look, don't touch." You choose if and when to hand it keys to anything more.

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.

---

Contents

• What this actually does
• 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
• Things you can try asking
• Testing it safely
• For developers
• What's next
• Built by BackCrew
• License

What this actually does

To be precise about what this is, because it's easy to overstate: this is not an all-knowing office assistant that understands your business and handles things for you. It's a specific, listed set of actions — "look up a customer," "schedule a job," "send an invoice" — 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.

That's still genuinely useful. Instead of this:

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

You can just say:

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

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

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 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 generate it from your own Housecall Pro account (steps below) and never share it.
• Terminal — a plain-text window where you type commands instead of clicking buttons. Setup involves a few terminal commands, listed step-by-step below.
• 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 badge metaphor from the top is the real architecture, not just a nice way of putting it:

• Out of the box, this server 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. There's no way to accidentally trigger a write action in the default setup, because the server doesn't expose them to the AI at all.
• When you're ready for more, you choose a badge level, not an all-or-nothing switch. Turning on write access (HCP_MCP_MODE=read_write — see setup) still requires picking a profile that caps what's allowed:
  • readonly-owner — same as the default. Look-ups only.
  • 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 in this mode.
  • 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 open more doors than intended. If the profile setting is ever misspelled or invalid, the server falls back to the safest option (read-only) rather than the most permissive one.

What it can look up (always safe)

These actions 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 in the default setup, with no extra steps:

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) — this section exists so you know exactly what you'd be turning on, not because it's 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

You'll need:

• A computer with Node.js installed (free software this project runs on)
• A Housecall Pro account on the MAX or XL plan (only needed once you're ready to connect to your real account — not needed to download and look at the project)

Step 1: Download the project

Open a terminal and type:

git clone https://github.com/jayson-svg/backcrew-mcp.git
cd backcrew-mcp
npm install
npm run build

Step 2: Get your Housecall Pro key

1. Log into your Housecall Pro account
2. Go to App Store → API Key Management → Generate
3. Copy the key it gives you

Housecall Pro's own instructions: Housecall Pro API docs.

Step 3: Save your key and choose your safety level

cp .env.example .env

Open the new .env file in any text editor:

HOUSECALL_PRO_API_KEY=paste_your_key_here

# Leave these two exactly as they are until you've read
# "Testing it safely" below and are ready for more than look-ups.
HCP_MCP_MODE=read_only
HCP_MCP_PROFILE=readonly-owner

Save the file. Keep it private — anyone with your key can access your Housecall Pro data.

Connecting it to Claude

Claude Desktop / Claude Code

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

{
  "mcpServers": {
    "housecall-pro": {
      "command": "node",
      "args": ["/absolute/path/to/backcrew-mcp/dist/index.js"],
      "env": {
        "HOUSECALL_PRO_API_KEY": "your_key_here",
        "HCP_MCP_MODE": "read_only",
        "HCP_MCP_PROFILE": "readonly-owner"
      }
    }
  }
}

Replace /absolute/path/to/backcrew-mcp with wherever you downloaded the project.

Restart Claude. You should see Housecall Pro show up as something Claude can use — with only the look-up actions available, by default.

This also works with 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 and when you decide to turn on write access, a few habits go a long way:

1. Start in read-only mode and stay there for a while. Get a feel for how the AI interprets your requests before you ever let it change anything.
2. When you do turn on office-ops, test on a clearly fake customer first. Create 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. Never go straight to admin mode. Deletes, voids, and locks are hard or impossible to undo. office-ops covers real day-to-day work without exposing any of that.
4. Never share your API key — in chat, in a screenshot, in a support ticket, anywhere. Treat it like a password, because it functions like one.
5. If something looks wrong, switch back to HCP_MCP_MODE=read_only immediately. That alone guarantees nothing further can be changed, regardless of what profile is set.

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/.

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 change 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

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.

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 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

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

License

MIT