toducthanh

Housecall Pro MCP

Terminal CLI 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.

---

Requirements

• Housecall Pro MAX plan account
• A Housecall Pro API key or OAuth credentials (how to get one)

---

Installation

There are two ways to use this tool. Choose the one that fits your workflow.

---

Option A — hcpro terminal CLI

A standalone terminal tool. One curl command installs everything — no manual config needed.

Requirements: Claude Code installed — macOS and Linux only (Windows not supported)

1. Install

curl -fsSL https://raw.githubusercontent.com/ToDucThanh/housecallpro-mcp/feature/cli/install.sh | sh

If ~/.local/bin is not in your $PATH, the installer will print the command to add it.

To pin to a specific version:

HCPRO_VERSION=v0.2.0 curl -fsSL https://raw.githubusercontent.com/ToDucThanh/housecallpro-mcp/feature/cli/install.sh | sh

2. Connect Housecall Pro

hcpro auth login

Choose your authentication method when prompted:

• API Key (recommended) — paste your Housecall Pro API key
• OAuth 2.0 (advanced) — enter your client ID and secret; a browser window opens for authorization

API key is recommended for most users. OAuth 2.0 requires registering http://localhost:7891/callback as an allowed redirect URI in your HCP developer dashboard app settings before running this command. If that step is skipped, the authorization will fail.

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

3. Connect Claude

hcpro auth claude login

Choose your Claude authentication method when prompted:

• API Key — paste your Anthropic API key (billed per token)
• Subscription — uses your existing Claude.ai Pro/Max subscription via Claude Code

This step is required even if you're already logged into Claude Code. It's not a re-authentication — it just registers which auth method hcpro should use. Choosing Subscription will be instant if you're already logged in.

4. Start using it

One-shot query:

hcpro "list my jobs today"
hcpro "find customer John Smith"
hcpro "show all open invoices"

Interactive session:

hcpro chat

Check auth status

hcpro auth status

Remove credentials

hcpro auth logout          # remove HCP credentials
hcpro auth claude logout   # remove Claude credentials from hcpro (does not sign out of Claude Code itself)

Update hcpro

Re-run the install script — it replaces the existing binary in place:

curl -fsSL https://raw.githubusercontent.com/ToDucThanh/housecallpro-mcp/feature/cli/install.sh | sh

Uninstall hcpro

rm -rf ~/.local/lib/hcpro ~/.local/bin/hcpro

Get help

hcpro --help
hcpro auth --help
hcpro auth claude --help

---

Option B — Claude Code plugin

For users who prefer to work entirely inside Claude Code.

Requirements: Claude Code installed, Node.js 20+

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 Marketplaces tab → select toducthanh → Browse plugins → find housecallpro-mcp → install it.

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

API key auth (recommended):

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

OAuth 2.0 (advanced):

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

OAuth for the plugin requires you to obtain an access token manually (e.g. from your HCP developer dashboard). There is no automatic token refresh — when the token expires you will need to update it manually in Configure options. API key is recommended.