housecall-pro-mcp

A local MCP (Model Context Protocol) server that wraps the Housecall Pro Public API (v1) 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

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:

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

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:

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)