Housecall Pro MCP

Housecall Pro MCP Server

An open-source MCP server for the Housecall Pro 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:

{

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

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:

/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.

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.

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.

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 --describe prints that command's parameters without running it.

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.

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.

1. 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 server follows whatever you generated, so a read-only key cannot reach the write tools at all. If you want an assistant that only answers questions, generate a read-only key and Housecall Pro enforces that limit for you.

Only an admin can generate a key, and admins have full account access, so the key reaches the whole account rather than one person's slice of it.

Tools

96 tools. Reading works with any key; writing needs a full-access one. They are grouped into toolsets, so an install can register only the groups it needs - see Choosing which tools to register.

Reading

| hcp_get_job_invoices | A single job's invoices, without