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.

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

95 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