backcrew-mcp-housecall-pro

# 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](https://www.housecallpro.com/) 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](#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](#what-this-actually-does) - [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 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](#how-to-set-it-up)) 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](#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](https://nodejs.org) 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: ```bash 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](https://docs.housecallpro.com). ### Step 3: Save your key and choose your safety level ```bash cp .env.example .env ``` Open the new `.env` file in any text editor: ```bash 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: ```json { "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/`](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)