Housecall Pro Mcp

Housecall Pro MCP

面向 Housecall Pro 公共 API 的终端命令行工具和 Claude Code 插件。 通过自然语言管理客户、预约工作、创建报价、跟踪发票、处理潜在客户等。

---

要求

• Housecall Pro MAX 计划账号
• Housecall Pro API 密钥或 OAuth 凭据（获取方式）

---

安装

有两种使用此工具的方式。请选择适合你的工作流的方式。

---

选项 A — hcpro 终端命令行工具

独立的终端工具。只需一条 curl 命令即可安装所有内容，无需手动配置。

**要求：**已安装 Claude Code — 仅支持 macOS 和 Linux（不支持 Windows）

1. 安装

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

如果 ~/.local/bin 不在你的 $PATH 中，安装程序会打印添加该路径的命令。

要固定到特定版本：

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

2. 连接 Housecall Pro

hcpro auth login

出现提示时，选择身份验证方式：

• API Key （推荐） — 粘贴你的 Housecall Pro API 密钥
• OAuth 2.0 （高级） — 输入客户端 ID 和密钥；随后会打开浏览器窗口进行授权

**建议大多数用户使用 API 密钥。**运行此命令前，OAuth 2.0 要求在 HCP 开发者控制面板的应用设置中，将 http://localhost:7891/callback 注册为允许的重定向 URI。如果跳过此步骤，授权将失败。

API 访问需要 MAX 计划。如果遇到 403 错误，请检查你的计划。

3. 连接 Claude

hcpro auth claude login

出现提示时，选择 Claude 身份验证方式：

• API Key — 粘贴你的 Anthropic API 密钥（按令牌计费）
• Subscription — 通过 Claude Code 使用你现有的 Claude.ai Pro/Max 订阅

即使你已经登录 Claude Code，也必须完成此步骤。这不是重新进行身份验证，而只是注册 hcpro 应使用的身份验证方式。如果你已经登录，选择 Subscription 后即可立即完成。

4. 开始使用

单次查询：

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

交互式会话：

hcpro chat

检查身份验证状态

hcpro auth status

移除凭据

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

更新 hcpro

重新运行安装脚本 — 它会直接替换现有二进制文件：

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

卸载 hcpro

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

获取帮助

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

---

选项 B — Claude Code 插件

适合希望完全在 Claude Code 中工作的用户。

**要求：**已安装 Claude Code，Node.js 20+

步骤 1 — 注册 Marketplace

/plugin marketplace add toducthanh/housecallpro-mcp

若仅对当前项目生效，请添加 --scope local。若要与所有仓库协作者共享，请添加 --scope project。

步骤 2 — 安装并配置插件

运行 /plugin → 打开 Marketplaces 选项卡 → 选择 toducthanh → Browse plugins → 找到 housecallpro-mcp → 安装。

安装后，前往 Installed 选项卡 → 选择 housecallpro-mcp → Configure options，然后输入你的凭据：

API key 身份验证 (推荐)：

选项	值
身份验证方式	apikey
Housecall Pro API key	你的 API key

OAuth 2.0 (高级)：

选项	值
身份验证方式	oauth
Housecall Pro client ID	你的 OAuth client ID
Housecall Pro client secret	你的 OAuth client secret
Housecall Pro OAuth token	你的 OAuth access token

插件的 OAuth 要求你手动获取 access token（例如，从 HCP 开发者面板获取）。系统不会自动刷新 token——token 过期后，你需要在 Configure options 中手动更新。推荐使用 API key。

你也可以通过 CLI 安装（默认使用用户范围）：

/plugin install housecallpro-mcp@toducthanh

然后通过 /plugin → Installed 选项卡 → Configure options 配置凭据。

运行 /reload-plugins 激活插件。

验证是否正常运行

在 Claude Code 中运行：

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

然后进行实时测试：

Use the housecallpro MCP to get my company information

---

获取 API key

1. 登录你的 Housecall Pro 账户
2. 前往 App Store → API Key Management → Generate
3. 复制密钥并妥善保管

API 访问需要 MAX 套餐。如果遇到 403 错误，请检查你的套餐。

---

用法 — 示例提示词

客户

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

预约与排程

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

估价单与发票

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

潜在客户

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

报告与批量操作

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

---

工作流指南

为现有客户预约工作

AI 会自动串联以下步骤：

1. list_customers → 查找 customer_id
2. list_customer_addresses → 查找 address_id
3. create_job → 创建工作
4. update_job_schedule → 安排时间
5. dispatch_job → 分配技术人员（可选）

示例提示词：

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

为全新客户预约工作

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

创建含多个选项的估价单

估价单采用两级结构——先创建 Options（选项），再在每个 Option（选项）中添加 Line Items（明细项）。

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

将潜在客户转为工作

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

---

字段格式

字段	有效格式	无效格式
日期	"2025-05-01T09:00:00"	"05/01/2025"、"next Monday"
电话号码	"+1 555 123 4567"	"555-PLUMBER"
工作状态	"scheduled"、"completed" 等	"done"、"pending"
金额	整数分——$150 = 15000	150.00
ID	非空字符串	""（空）

有效的工作状态值：unscheduled · scheduled · in_progress · completed · canceled

---

获取所有页面

多个列表工具支持 fetch_all: true，可自动获取所有页面：

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

支持的工具：list_customers、list_jobs、list_estimates、list_leads、 list_invoices、list_employees、list_events、list_tags、list_materials、 list_pricebook_services

默认最多获取 20 页（约 200 条记录）。如需获取更大的数据集，请使用明确指定的 page + page_size。

---

错误参考

错误	原因	修复方法
HCP API Error (401)	API 密钥错误或缺失	检查 HOUSECALL_API_KEY
HCP API Error (403)	未使用 MAX 套餐	升级套餐或检查 HOUSECALL_AUTH_METHOD
HCP API Error (404)	ID 错误或端点不可用	仔细检查 ID
HCP API Error (422)	缺少必填字段	检查必填参数
HCP API Error (429)	触发速率限制	服务端会自动重试——请稍候再试
Must be ISO 8601 format	日期格式错误	使用 "2025-05-01T09:00:00"
Must be a valid phone number	电话号码无效	使用 "+1 555 123 4567"
ID cannot be empty	ID 为空字符串	先获取正确的 ID
/skills 显示为空	插件未加载	重新执行步骤 1 和 2，然后运行 /reload-plugins
/mcp 中未显示 housecallpro	MCP 未启动	前往 /plugin → Installed → Configure options，并验证凭据
HCP credentials not configured	未运行 hcpro auth login	运行 hcpro auth login
Claude credentials not configured	未运行 hcpro auth claude login	运行 hcpro auth claude login
claude binary not found	未安装 Claude Code	从 claude.ai/code 安装

---

已知限制

• Pipeline 只能向前推进——无法设置顺序更靠前的状态
• 可用性/预订时段端点——使用 get_booking_windows 获取可用时段
• 估价单使用 Options → Line Items（不像 Jobs 那样直接操作）
• 材料需要 material_category_uuid——请先调用 list_material_categories
• 付款处理无法通过公共 API 使用，请使用 HCP 控制面板
• fetch_all 默认最多处理 20 页
• 速率限制未由 HCP 公布；服务端会采用退避机制自动重试，最多 3 次

---

工具概览

涵盖所有 Housecall Pro API 资源的 70 多个工具：

资源	工具
客户	列出、获取、创建、更新、地址
Jobs	列出、获取、创建、安排、派遣、行项目、备注、标签、锁定、发票
估价单	列出、获取、创建、选项、行项目、批准
发票	列出、获取、预览
潜在客户	列出、获取、创建、转换、行项目
员工	列出
标签	列出、创建、更新、删除
事件	列出、获取
材料	列出、创建、更新、删除
Price Book	服务、价格表
Pipeline	状态、更新状态
路线	列出
公司	获取、排期时段、预订时段
Webhook	订阅、取消订阅
应用程序	获取、启用、禁用

---

开发

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

**快速迭代：**仅为当前会话加载插件，无需安装：

claude --plugin-dir .

在会话中使用 /reload-plugins，无需重启即可加载更改。

CLI 开发

cd cli
bun install
bun test                  # run all tests
bun run dev               # run CLI in dev mode (no build needed)

在开发模式下运行命令：

bun run src/index.ts auth status
bun run src/index.ts "list my jobs today"
bun run src/index.ts chat

在本地构建二进制文件：

bun run build:darwin-arm64   # macOS Apple Silicon
bun run build:darwin-x64     # macOS Intel
bun run build:linux-x64      # Linux x64
bun run build:linux-arm64    # Linux ARM

二进制文件会输出到 ../dist/。

完整安装流程测试：

# 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

测试后清理：

选项 A — 移除 marketplace（同时移除插件）：

claude plugin marketplace remove toducthanh --scope local

选项 B — 先卸载插件，再移除 marketplace：

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

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

然后移除 marketplace：

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

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

---

链接

• Housecall Pro API 文档
• npm 软件包
• GitHub 仓库
• GitHub 发行版
• Model Context Protocol
• Claude Code

---

许可证

代码依据 General Public License v3.0 发布。