housecall-pro-mcp

<!-- mcp-name: io.github.hcpapi/housecall-pro-mcp -->

# Housecall Pro MCP Server

An open-source MCP server for the [Housecall Pro](https://www.housecallpro.com)
API. Connect Claude, ChatGPT, Cursor, or any MCP-compatible AI agent to your
Housecall Pro account, so you can ask for what you need instead of clicking
through reports.

Independent project, not affiliated with, endorsed by, or sponsored by Housecall
Pro. We run a service company on Housecall Pro ourselves, which is why it exists.

## Install

Needs Node 18 or newer and a Housecall Pro API key. API access comes with the
MAX plan and is not available on lower tiers.

**Claude Desktop.** Open **Settings**, then **Developer**, then **Edit Config**,
and add:

```json
{
  "mcpServers": {
    "housecall-pro": {
      "command": "npx",
      "args": ["-y", "housecall-pro-mcp"],
      "env": { "HCP_API_KEY": "your-api-key-here" }
    }
  }
}
```

Restart Claude Desktop and the Housecall Pro tools will appear.

**Claude Code.** Add it directly:

```bash
claude mcp add housecall-pro -e HCP_API_KEY=your-api-key-here -- npx -y housecall-pro-mcp
```

Or install it as a plugin, which prompts for the key (stored in your keychain, never
in a config file) and exposes the read-only and toolset switches as install-time options:

```bash
/plugin marketplace add hcpapi/housecall-pro-mcp
/plugin install housecall-pro@hcpapi
```

**Cursor, Codex, and other MCP clients.** Any client that speaks MCP over stdio
works. Use `npx` as the command, `["-y", "housecall-pro-mcp"]` as the arguments,
and put `HCP_API_KEY` in the environment.

Getting a key takes about a minute and is described under
[Getting your Housecall Pro API key](#getting-your-housecall-pro-api-key).

## Housecall Pro API quirks, and what this server does about them

These are the edges of the Housecall Pro API itself. Each one is a place an
integration built from the documentation alone gets a wrong answer rather than
an error.

| What the API does | What this server does about it |
|---|---|
| Money is integer cents, so $250 is `25000`. | Converts in both directions. $250 stays $250 and never arrives as $2.50. |
| `PATCH /jobs` answers **200 and changes nothing** when sent a flat schedule key, a description, or tags. | Sends only the nested schedule object the API honours, so a reported success is a real one. |
| A job's description is derived from its line items and cannot be set directly. | Exposes line-item writes rather than a description field that would silently do nothing. |
| Invoices filter on `created_at`, `due_at`, `paid_at` and `amount_due`, but not on `service_date` or `invoice_date`. An unsupported filter name is accepted and ignored rather than refused. | Uses the names the endpoint actually takes, and walks a service-date window client-side because no server-side equivalent exists. |
| `work_status` reads back in a different vocabulary than it is written, for example `complete unrated` rather than `completed`. | Normalises on read, so a status filter matches real records instead of nothing. |
| Deleted jobs still appear in list responses and count toward totals. | Surfaces `deleted_at` on every row and warns, so revenue is not overstated. |
| Removing a tag from a job answers with an empty success whether or not the tag was there. | Reports the request as accepted rather than claiming a removal it cannot confirm. |
| An archived job refuses to describe its appointments. | Flags the job as archived and returns an empty list, so a sweep never stops part way. |
| The invoice document is a very long HTML page, not a PDF. | Returns the opening of the page and says how much of it that was. |
| Attachments have no route of their own — `GET` on a job's attachments path serves an HTML 404 — but `expand[]=attachments` returns them with a signed download link. | Asks with `expand` and hands back the files. The link is minted per request, so it is fetched when given and never stored. |
| Some routes answer only on `PUT`, and a `POST` to the same path returns an HTML 404 page, which reads as "no such route" rather than as the wrong method. | Uses the method each route actually takes, so dispatching a crew and bulk line-item updates work instead of looking absent. |

**Never trust a 2xx on a Housecall Pro write.** Read the record back. Several
routes answer 200 without changing anything, which is why the rows above exist.

## The `hcp` command line

The same package installs `hcp`, which reaches the same Housecall Pro surface
from a terminal. It is the same code — every command is one of the tools below,
with the same conversions, the same filters and the same refusals.

It exists because an MCP server only runs while an assistant is in the room.
A scheduled task that writes an aging report every Monday morning is not
something an MCP client can do.

```bash
npm install -g housecall-pro-mcp     # or run it once with: npx -p housecall-pro-mcp hcp
export HCP_API_KEY=your-api-key-here

hcp list jobs --work-status completed --page-size 20
hcp jobs list --page-size 20                    # the same command, read either way round
hcp get customer cus_1a2b3c
hcp search customers "smith"
hcp list invoices --csv > unpaid.csv
```

Windows, macOS and Linux, wherever Node 18+ runs.

**Output.** A table sized to your terminal by default, `--json` for the full
records, `--csv` for a spreadsheet or a scheduled export. Data goes to stdout and
commentary to stderr, so a redirect gets the data and nothing else.

**Before you change anything.** `--dry-run` prints exactly what a command would
send and sends nothing. `--read-only` refuses any command that could change your
account, and says which switch stopped it.

**Finding your way around.** `hcp` on its own lists the commands by group.
`hcp commands` prints them one per line, and `hcp commands --json` gives the
whole table, including which ones write. `hcp <command> --describe` prints that
command's parameters without running it.

```bash
hcp create customer --first-name Alex --last-name Rivera --dry-run
hcp list jobs --describe
```

Every switch below that applies to the server applies here too, including
`--toolsets`.

## Documented routes that do not exist

Housecall Pro's published documentation describes these. They are not there. An
integration built from the docs alone ships broken code paths for each one.

| Documented | Reality |
|---|---|
| `POST`, `PUT`, `DELETE /appointments` | Absent. Appointments exist only nested under a job. |
| `PUT /jobs/{id}` | Absent. `PATCH /jobs` honours only the nested schedule object. |
| `POST /invoices` | Absent. |
| `DELETE /customers/{id}` | Absent. There is no public customer delete. |
| `PUT` or `DELETE /customers/{id}/addresses/{adr}` | Absent. Addresses are append-only. |
| `PUT` or `DELETE /estimates/{id}` and `/estimates/{id}/options/{opt}` | Absent. |
| `PUT` or `DELETE /leads/{id}` | Absent as writes: a lead cannot be updated or deleted. Reading works — `GET /leads`, `GET /leads/{id}` and `GET /leads/{id}/line_items` are all live. |
| `DELETE /tags/{id}` | Absent. A tag can never be deleted through the API. |
| `DELETE /jobs/{id}/tags` | Absent. |
| `PUT /jobs/{id}/lock` | The verb is absent, not the route: `POST /jobs/{id}/lock` locks one job. The bulk `POST /jobs/lock` also exists and keys on `starting_at` rather than a list of job ids. |
| `POST /api/price_book/services` | Absent. Materials and categories create normally. |
| `GET /webhooks/subscription` | Absent. |
| `GET /employees/{id}` | Absent. There is no employee detail route — an id that `GET /employees` just returned serves an HTML 404. Read the row from the listing. |

## What you can ask

- "How much did we invoice in June, grouped by service?"
- "List this week's scheduled jobs with outstanding balances"
- "Pull up the customer record for the Smiths on Elm Street"
- "Which customers are tagged 'Service Plan'?"
- "Export Q2 invoices as CSV"
- "What's in our price book for water heaters?"
- "When is job_123 booked, and who is going?"
- "Show me invoice_123 the way the customer sees it"
- "Add a new customer: John Baker, 22 Elm St, Springfield IL, +1 555 123 4567"
- "Draft a good/better/best estimate for cus_123: water heater replacement at
  $2,400 / $3,100 / $3,900"
- "Book Tuesday 8-10am on job_123 for Mike"
- "Move that visit to Thursday morning and put Dave on it instead"
- "Dispatch Mike and Dave to job_123"
- "Reprice every labor line on job_123 in one go"
- "The customer went with the middle option on that estimate - mark it approved"
- "What hours do we work, and what's free next week?"
- "Default our jobs to 90 minutes with a two-hour arrival window"

## Getting your Housecall Pro API key

1. Sign in to Housecall Pro as an admin. Office staff logins cannot generate
   keys.
2. Open **My Apps**, the grid icon in the top bar
3. Click **Go to App store**, search for API, and open **API Key Management**.
   It will usually not be sitting in the My Apps menu already, because that
   menu lists a subset rather than the whole catalogue.
4. Click **Generate new API key**, name it, and choose its access level:
   - Read-only, for reporting, lookups and exports. It refuses writes across the
     account **with one exception we have measured**: the price-book routes under
     `/api/price_book/` are not covered by that gate, and a read-only key can
     create and delete price-book categories there. If you want a guarantee
     rather than nearly one, run this server with `--read-only`, which does not
     register a write tool at all.
   - Full access, which also allows creating customers, jobs and estimates.
5. Copy the key. Housecall Pro keeps it visible on that page afterwards, so you
   can come back and copy it again. What you cannot do is edit a key: changing
   the access level means generating a new one and deleting the old.

The walkthrough with screenshots is at <https://hcpapi.com/mcp/#key>.

The access level you pick is the real boundary. This serve