# housecall-pro-mcp

A local MCP (Model Context Protocol) server that wraps the [Housecall Pro Public API (v1)](https://docs.housecallpro.com/) so Claude Desktop or Claude Code can read and write your Housecall Pro data directly.

Built for personal/local use — it talks to Housecall Pro with a single API key, runs over stdio, and is meant to be added to your own Claude Desktop / Claude Code config.

## Before you start

Housecall Pro's own docs and third-party sources disagree on whether full API access requires their **MAX** plan or is available on lower Pro tiers — that's account-specific. Check your own account: **Housecall Pro → Settings → API / App Store card.** If you don't see an option to generate an API key there, you may need to request API access from Housecall Pro support first.

## Setup

```bash
npm install
cp .env.example .env
# edit .env and paste your real HCP_API_KEY
npm run build
```

### Add to Claude Desktop

Edit your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS) and add:

```json
{
  "mcpServers": {
    "housecall-pro": {
      "command": "node",
      "args": ["/absolute/path/to/housecall-pro-mcp/dist/src/index.js"],
      "env": {
        "HCP_API_KEY": "your_housecall_pro_api_key_here"
      }
    }
  }
}
```

Restart Claude Desktop after saving.

### Add to Claude Code

```bash
claude mcp add housecall-pro --env HCP_API_KEY=your_housecall_pro_api_key_here -- node /absolute/path/to/housecall-pro-mcp/dist/src/index.js
```

## Tools

All 23 documented Housecall Pro v1 endpoints are wrapped. Each tool's description links to the exact Housecall Pro docs page for that endpoint — worth checking before using `create_*`/`update_*` tools, since their `body` argument is passed straight through rather than hard-coded (see "A note on accuracy" below).

| Area      | Tools |
|-----------|-------|
| Company   | `get_company`, `get_schedule_windows` |
| Customers | `list_customers`, `get_customer`, `create_customer`, `update_customer` |
| Jobs      | `list_jobs`, `get_job`, `create_job`, `update_job_schedule` |
| Estimates | `list_estimates`, `get_estimate`, `create_estimate`, `bulk_update_estimate_option_line_items` |
| Invoices  | `list_invoices`, `list_job_invoices`, `get_invoice`, `preview_invoice` |
| Employees | `list_employees` |
| Leads     | `list_leads`, `get_lead`, `create_lead`, `convert_lead` |

All `list_*` tools accept `page`, `page_size`, `sort_by`, `sort_direction`, plus an `extra_query` object for any endpoint-specific filters (e.g. `customer_id`, `work_status`) not modeled explicitly.

## Bulk export (for the ServiceTitan migration)

For pulling everything out of Housecall Pro in one shot rather than one call at a time through chat, there's a standalone script:

```bash
npm run export-all
```

This pages through customers, jobs, estimates, invoices, employees, and leads, and writes:

- `export/<resource>.json` — full raw records
- `export/<resource>.csv` — flattened, spreadsheet-friendly version

It's a plain script (not an MCP tool) on purpose — paginating through potentially thousands of records and returning them through a single chat tool call would blow past reasonable response sizes. Run it directly, then hand the CSVs/JSON to whatever process you're using to load data into ServiceTitan.

**Heads up:** the script guesses the response shape of each list endpoint (e.g. assumes `GET /customers` returns `{ customers: [...] }`). If Housecall Pro's actual shape differs, it won't silently produce a broken export — it stops for that resource and writes the raw first-page response to `export/_debug_<resource>_page1.json` so you can see the real shape. Check your terminal output after running it.

## A note on accuracy

This was built from Housecall Pro's public docs and a third-party consolidated API reference, not by testing against a live account (I don't have your API key). Everything here should work as documented, but:

- The exact JSON field names Housecall Pro expects in `create_job`, `create_customer`, `create_estimate`, `create_lead`, `update_customer`, `update_job_schedule`, and `bulk_update_estimate_option_line_items` request bodies were **not** hard-coded into schemas here, specifically so nothing gets guessed/fabricated. Each of those tools takes a raw `body` object and links to the exact docs page — check the docs (or make one test call and read the error message) before relying on it.
- List-endpoint filter params beyond pagination/sorting (e.g. `customer_id` on jobs) aren't hard-coded either — use `extra_query` and confirm the param name against the linked docs.
- First real call against your account is the actual test. If something 404s or the auth header format is wrong, the error message will include Housecall Pro's own response body, which should point at the fix.

## Project layout

```
src/
  housecallClient.ts   Thin fetch wrapper (auth header, pagination, error handling)
  index.ts             MCP server + all 23 tool registrations
scripts/
  export-all.ts        Bulk JSON/CSV export script (see above)
```