# housecallpro-mcp

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![MCP](https://img.shields.io/badge/MCP-compatible-green.svg)](https://modelcontextprotocol.io)

MCP server for [Housecall Pro](https://housecallpro.com), the mid-market trades vertical SaaS (HVAC, plumbing, electrical, garage, pest, landscaping). 5 tools for AI agents to register new customers, schedule jobs, create estimates, log inbound leads, and generate invoices (env-gated) against active jobs.

As of May 2026, Housecall Pro does not ship an official MCP server. Two low-visibility community attempts exist. This is the production-quality, install-ready Python rail.

## The 5 tools

| Tool | Purpose | Gated? |
|---|---|---|
| `create_pro_customer` | Register a new customer in the CRM | No, safe |
| `schedule_new_job` | Schedule a new trade job for an existing customer | No, safe |
| `create_estimate` | Generate a pricing estimate or proposal | No, safe |
| `submit_new_lead` | Log a new marketing or inbound prospect lead | No, safe |
| `generate_job_invoice` | Post an official invoice against an active job | YES, `HOUSECALLPRO_ALLOW_INVOICE=true` required |

## Install

```bash
pip install housecallpro-mcp
```

## Configure

```bash
export HOUSECALLPRO_API_KEY="your-housecallpro-api-key"
export HOUSECALLPRO_ALLOW_INVOICE="false"   # set to "true" to enable invoice creation
```

Get an API key in your Housecall Pro account settings. The key is sent as a Bearer token; keep it server-side.

## Use with Claude Desktop

```json
{
  "mcpServers": {
    "housecallpro": {
      "command": "housecallpro-mcp",
      "env": {
        "HOUSECALLPRO_API_KEY": "your-housecallpro-api-key",
        "HOUSECALLPRO_ALLOW_INVOICE": "false"
      }
    }
  }
}
```

Restart Claude Desktop. The 5 Housecall Pro tools are now available.

## Use case: AI receptionist + sales agent for a trades business

Typical agent flow for inbound calls and quotes:

1. Call `create_pro_customer(first_name, last_name, mobile_phone)` to register the caller in CRM
2. Call `schedule_new_job(customer_id, description, start_time, end_time)` to book the service window
3. After the diagnostic call: `create_estimate(customer_id, note)` to propose pricing
4. For web-form / chat inbound: `submit_new_lead(customer_id, description)` to log the prospect in the sales funnel
5. (After job completion + with `HOUSECALLPRO_ALLOW_INVOICE=true`): `generate_job_invoice(job_id)` to bill the customer

## Safety note

The invoice action is intentionally gated behind an explicit env var. The default install does not bill customers. Set `HOUSECALLPRO_ALLOW_INVOICE="true"` only when the AI agent workflow has been explicitly approved for billing actions.

## Architecture

- Public MIT-licensed wrapper around the Housecall Pro REST API
- Async HTTP via `httpx`
- pydantic v2 input validation
- Bearer API key auth, server-side only
- Rate-limit aware (429 returns a clean error)
- Invoice action gated by env flag

## Development

```bash
git clone https://github.com/NoBanks/housecallpro-mcp.git
cd housecallpro-mcp
pip install -e ".[dev]"
pytest
```

## License

MIT. See [LICENSE](LICENSE).

## Author

Ryan Hammer (NoBanks). Solo founder + engineer. Built this and 14 other MCP servers as part of a sprint to expose AI agent rails for the products and platforms shipping daily.

- GitHub: [@NoBanks](https://github.com/NoBanks)
- X/Twitter: [@livingagentic](https://x.com/livingagentic)
- Site: [livingagentic.me](https://livingagentic.me), [nohumannearby.com](https://nohumannearby.com)

Open to AI engineering roles, contract or full-time, remote-only.