Housecall Pro MCP

MCP server and Claude Code plugin for the Housecall Pro public API. Manage customers, book jobs, create estimates, track invoices, handle leads and more — all from natural language in Claude Code.

Requirements

• Claude Code installed
• Housecall Pro MAX plan account
• A Housecall Pro API key (how to get one)
• Node.js 20+

Installation - 2 steps

Step 1 — Register the marketplace

/plugin marketplace add toducthanh/housecallpro-mcp

To scope to the current project only, add --scope local. To share with all repo collaborators, add --scope project.

Step 2 — Install and configure the plugin

Run /plugin → open the Discover tab → find housecallpro-mcp → install it.

After install, go to the Installed tab → select housecallpro-mcp → Configure options and enter your credentials:

API key auth:

| Option | Value | |---|---| | Authentication method | apikey | | Housecall Pro API key | your API key |

OAuth 2.0:

| Option | Value | |---|---| | Authentication method | oauth | | Housecall Pro client ID | your OAuth client ID | | Housecall Pro client secret | your OAuth client secret | | Housecall Pro OAuth token | your OAuth access token |

You can also install via CLI (user scope by default):

/plugin install housecallpro-mcp@toducthanh

Then configure credentials through /plugin → Installed tab → Configure options.

Run /reload-plugins to activate the plugin.

Verify it's working

Run inside Claude Code:

/skills    ← should list housecallpro
/mcp       ← should show housecallpro connected

Then try a live test:

Use the housecallpro MCP to get my company information

Getting your API key

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

API access requires the MAX plan. If you get a 403 error, check your plan.

Usage — Example prompts

Customers

List my first 10 customers
Find customer named "John Smith"
Create a customer Jane Doe with email [email protected] and mobile +1 555 123 4567
Get all addresses for customer {customer_id}
Fetch all customers with fetch_all true and tell me the total count

Booking & scheduling

Book a job for customer {customer_id} at address {address_id} on 2025-05-01 at 9am for 1 hour
Find customer John Smith, get his address, create a job and schedule it for next Monday 9am
Reschedule job {job_id} to 2025-05-10 at 2pm and notify the customer
Dispatch job {job_id} to employee {employee_id}
List all scheduled jobs for this week
List all unscheduled jobs
Get available booking windows for the next 7 days

Estimates & invoices

Create an estimate for customer {customer_id} at address {address_id}
Add an option "Standard Package" with a labor line item to estimate {estimate_id}
Approve estimate option {option_id}
List all open invoices
Get all invoices for job {job_id}
List invoices created between 2025-01-01 and 2025-03-31

Leads

Create a lead for customer {customer_id}
List all open leads
Convert lead {lead_id} to a job

Reporting & bulk

Fetch all completed jobs with fetch_all true for Q1 2025
Fetch all customers with fetch_all true and count how many have no address
List all employees
Get company information

Workflow guides

Book a job for an existing customer

Claude Code will automatically chain these steps:

1. list_customers → find customer_id
2. list_customer_addresses → find address_id
3. create_job → create the job
4. update_job_schedule → schedule it
5. dispatch_job → assign a technician (optional)

Example prompt:

Find customer John Smith, get his first address, create a job there
scheduled for 2025-05-01 9am-10am with 60 min arrival window,
notify the customer, and dispatch to employee Mike Johnson

Book a job for a brand new customer

Create a new customer Sarah Connor, phone +1 555 999 0000,
add her address 123 Main St Austin TX 78701,
then book a job there for 2025-05-02 at 2pm for 2 hours

Create an estimate with options

Estimates use a two-level structure — Options first, then Line Items inside each Option.

Create an estimate for customer {customer_id} at address {address_id},
add an option called "Standard Package" with a labor line item at $150,
then approve it

Lead to job conversion

Create a lead for customer {customer_id},
show me the pipeline statuses,
move it to the next status,
then convert it to a job and schedule it for next Monday at 10am

Field formats

| Field | Valid format | Invalid | |---|---|---| | Dates | "2025-05-01T09:00:00" | "05/01/2025", "next Monday" | | Phones | "+1 555 123 4567" | "555-PLUMBER" | | Work status | "scheduled", "completed" etc | "done", "pending" | | Money | Integer cents — $150 = 15000 | 150.00 | | IDs | Non-empty strings | "" (empty) |

Valid work status values: unscheduled · scheduled · in_progress · completed · canceled

Fetch all pages

Several list tools support fetch_all: true to automatically retrieve all pages:

Fetch all customers with fetch_all true
Fetch all completed jobs with fetch_all true from 2025-01-01 to 2025-03-31

Supported on: list_customers, list_jobs, list_estimates, list_leads, list_invoices, list_employees, list_events, list_tags, list_materials, list_pricebook_services

Capped at 20 pages (~200 records) by default. Use explicit page + page_size for larger datasets.

Error reference

| Error | Cause | Fix | |---|---|---| | HCP API Error (401) | Bad or missing API key | Check HOUSECALL_API_KEY | | HCP API Error (403) | Not on MAX plan | Upgrade plan or check HOUSECALL_AUTH_METHOD | | HCP API Error (404) | Wrong ID or unavailable endpoint | Double-check the ID | | HCP API Error (422) | Missing required field | Check required params | | HCP API Error (429) | Rate limited | Server auto-retries — wait and retry | | Must be ISO 8601 format | Wrong date format | Use "2025-05-01T09:00:00" | | Must be a valid phone number | Invalid phone | Use "+1 555 123 4567" | | ID cannot be empty | Empty string as ID | Fetch the correct ID first | | /skills shows nothing | Plugin not loaded | Re-run steps 1 & 2, then /reload-plugins | | /mcp doesn't show housecallpro | MCP not started | Go to /plugin → Installed → Configure options and verify credentials |

Known limitations

• Pipeline moves forward only — you cannot set a lower-order status
• Availability/booking slot endpoints — use get_booking_windows for available slots
• Estimates use Options → Line Items (not direct like Jobs)
• Materials require material_category_uuid — call list_material_categories first
• Payment processing — not available via public API, use HCP dashboard
• fetch_all is capped at 20 pages by default
• Rate limits — not published by HCP; server auto-retries up to 3 times with backoff

Tools overview

70+ tools across all Housecall Pro API resources:

| Resource | Tools | |---|---| | Customers | list, get, create, update, addresses | | Jobs | list, get, create, schedule, dispatch, line items, notes, tags, lock, invoices | | Estimates | list, get, create, options, line items, approve | | Invoices | list, get, preview | | Leads | list, get, create, convert, line items | | Employees | list | | Tags | list, create, update, delete | | Events | list, get | | Materials | list, create, update, delete | | Price Book | services, price forms | | Pipeline | statuses, update status | | Routes | list | | Company | get, schedule windows, booking windows | | Webhooks | subscribe, unsubscribe | | Application | get, enable, disable |

Development

git clone https://github.com/toducthanh/housecallpro-mcp
cd housecallpro-mcp
npm install
npm run generate-types   # generate types from housecall_v1.yaml
npm run build
npm run dev

Fast iteration: load the plugin for the current session only, no install needed:

claude --plugin-dir .

Use /reload-plugins inside the session to pick up changes without restarting.

Full install flow test:

# Register the local marketplace scoped to this project only
claude plugin marketplace add ./ --scope local

# Then in Claude Code: /plugin → Discover → install housecallpro-mcp → Configure options

To clean up after testing:

Option A — Remove the marketplace (removes the plugin too):

claude plugin marketplace remove toducthanh --scope local

Option B — Uninstall the plugin first, then remove the marketplace:

# Via CLI
claude plugin uninstall housecallpro-mcp --scope local

# Or via UI: /plugin → Installed tab → select housecallpro-mcp → Uninstall

Then remove the marketplace:

# Via CLI
claude plugin marketplace remove toducthanh --scope local

# Or via UI: /plugin → Marketplaces tab → select toducthanh → Remove

Links

• Housecall Pro API Docs
• npm package
• GitHub repo
• Model Context Protocol
• Claude Code

License

Code released under the MIT License.