housecall-pro-mcp

Housecall Pro MCP 服务

一个面向 Housecall Pro API 的开源 MCP 服务。将 Claude、ChatGPT、Cursor 或任何兼容 MCP 的 AI Agent 连接到你的 Housecall Pro 账户，这样你只需提出需求，而不必逐项点击查看报表。

这是一个独立项目，与 Housecall Pro 无关联，也未获得其认可或赞助。我们自己也在 Housecall Pro 上运营一家服务公司，这就是这个项目存在的原因。

安装

需要 Node 18 或更高版本，以及一个 Housecall Pro API 密钥。API 访问权限包含在 MAX 套餐中，较低级别的套餐不提供此权限。

Claude Desktop。 打开 Settings，然后依次选择 Developer 和 Edit Config， 再添加：

{
  "mcpServers": {
    "housecall-pro": {
      "command": "npx",
      "args": ["-y", "housecall-pro-mcp"],
      "env": { "HCP_API_KEY": "your-api-key-here" }
    }
  }
}

重启 Claude Desktop，Housecall Pro 工具就会显示出来。

Claude Code。 直接添加：

claude mcp add housecall-pro -e HCP_API_KEY=your-api-key-here -- npx -y housecall-pro-mcp

或者将其安装为插件。安装时会提示输入密钥（密钥存储在你的密钥链中，绝不会 存储在配置文件中），并提供只读和工具集开关作为安装时选项：

/plugin marketplace add hcpapi/housecall-pro-mcp
/plugin install housecall-pro@hcpapi

Cursor、Codex 和其他 MCP 客户端。 任何通过 stdio 使用 MCP 通信的客户端 都可以使用。将 npx 设为命令，将 ["-y", "housecall-pro-mcp"] 设为参数， 并在环境中设置 HCP_API_KEY。

获取密钥只需约一分钟，具体说明见 获取 Housecall Pro API 密钥。

Housecall Pro API 的特殊情况，以及本服务如何应对

以下是 Housecall Pro API 本身的一些特殊情况。仅根据文档构建的集成在这些情况下会给出错误答案，而不是返回错误。

API 的行为	本服务的应对方式
金额以整数美分表示，因此 $250 是 25000。	双向转换。$250 仍是 $250，绝不会变成 $2.50。
发送扁平的排期键、描述或标签时，PATCH /jobs 会返回 200，但不做任何更改。	只发送 API 会认可的嵌套排期对象，因此报告的成功确实会生效。
工单的描述由其明细项生成，无法直接设置。	提供明细项写入功能，而不提供一个只会静默失效的描述字段。
发票支持按 created_at、due_at、paid_at 和 amount_due 筛选，但不支持按 service_date 或 invoice_date 筛选。未支持的筛选名称会被接受并忽略，而不是被拒绝。	使用接口实际接受的名称；由于没有等效的服务端筛选方式，因此在客户端遍历服务日期范围。
work_status 读回时使用的词汇与写入时不同，例如返回 complete unrated 而不是 completed。	读取时进行标准化，使状态筛选能够匹配实际记录，而不是一无所获。
已删除的工单仍会出现在列表响应中，并计入总数。	在每一行中显示 deleted_at 并发出警告，避免高估收入。
从工单中移除标签时，无论该标签原本是否存在，都会返回空的成功响应。	将请求报告为已接受，而不声称已完成无法确认的移除操作。
已归档的工单无法返回其预约信息。	将工单标记为已归档并返回空列表，因此遍历过程不会中途停止。
发票文档是一个很长的 HTML 页面，而不是 PDF。	返回页面开头部分，并说明该部分的长度。
附件没有独立路由，对工单附件路径执行 GET 会返回 HTML 404，但 expand[]=attachments 会连同签名下载链接一起返回附件。	使用 expand 请求附件并返回文件。链接按请求生成，因此会在收到时获取，绝不会存储。
有些路由只接受 PUT，而对同一路径发送 POST 会返回 HTML 404 页面，让人以为“没有这个路由”，而不是方法不正确。	使用各路由实际接受的方法，因此派遣团队和批量更新明细项能够正常工作，而不会看起来像是路由不存在。

绝不要轻信 Housecall Pro 写入操作返回的 2xx。 读取记录以确认结果。有几个路由会在没有任何更改的情况下返回 200，这就是上表存在的原因。

hcp 命令行

同一个软件包还会安装 hcp，可从终端访问同一套 Housecall Pro 功能。它使用的是同一份代码：每条命令都对应下方的一个工具，采用相同的转换、筛选和拒绝规则。

之所以提供它，是因为 MCP 服务只有在助手在场时才会运行。每周一早上生成一份逾期报告的定时任务，并不是 MCP 客户端能完成的事。

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 和 Linux，只要能运行 Node 18+ 即可。

输出。 默认输出适合终端大小的表格，使用 --json 输出完整记录，使用 --csv 输出电子表格或定时导出所需的数据。数据写入 stdout，说明信息写入 stderr，因此重定向时只会获取数据，不会包含其他内容。

更改前的准备。 --dry-run 会准确打印命令将要发送的内容，但不会发送任何内容。--read-only 会拒绝任何可能更改你账户的命令，并说明是哪个开关阻止了操作。

熟悉用法。 单独运行 hcp 会按组列出命令。hcp commands 会逐行打印命令，hcp commands --json 会输出完整表格，其中包括哪些命令会写入数据。运行 hcp <command> --describe 会打印该命令的参数，而不会执行它。

hcp create customer --first-name Alex --last-name Rivera --dry-run
hcp list jobs --describe

以下所有适用于服务端的开关也适用于此处，包括 --toolsets。

文档中提及但实际不存在的路由

Housecall Pro 发布的文档介绍了以下路由，但它们实际上并不存在。仅根据文档构建的集成，每条路由都会导致代码路径失效。

文档所述	实际情况
POST、PUT、DELETE /appointments	不存在。预约仅作为作业的嵌套内容存在。
PUT /jobs/{id}	不存在。PATCH /jobs 仅支持嵌套的 schedule 对象。
POST /invoices	不存在。
DELETE /customers/{id}	不存在。没有公开的客户删除接口。
PUT 或 DELETE /customers/{id}/addresses/{adr}	不存在。地址只能追加，不能修改或删除。
PUT 或 DELETE /estimates/{id} 和 /estimates/{id}/options/{opt}	不存在。
PUT 或 DELETE /leads/{id}	写入接口不存在：无法更新或删除潜在客户。读取接口可用：GET /leads、GET /leads/{id} 和 GET /leads/{id}/line_items 均正常运行。
DELETE /tags/{id}	不存在。无法通过 API 删除标签。
DELETE /jobs/{id}/tags	不存在。
PUT /jobs/{id}/lock	路由存在，但不支持该 HTTP 方法：POST /jobs/{id}/lock 可锁定单个作业。批量接口 POST /jobs/lock 也存在，其依据是 starting_at，而不是作业 ID 列表。
POST /api/price_book/services	不存在。材料和类别可以正常创建。
GET /webhooks/subscription	不存在。
GET /employees/{id}	不存在。没有员工详情路由：GET /employees 刚返回的 ID 会显示 HTML 404。请从列表中读取对应行。

你可以这样提问

• “按服务类别汇总我们 6 月的开票金额。”
• “列出本周已安排且仍有未结余额的作业。”
• “调出 Elm Street 上 Smith 一家的客户记录。”
• “哪些客户被标记为‘服务计划’？”
• “将第二季度的发票导出为 CSV。”
• “我们的价格目录里，热水器的价格是多少？”
• “job_123 预约在什么时候？谁会去？”
• “按客户看到的样子展示 invoice_123。”
• “添加一位新客户：John Baker，地址是 Springfield IL 的 22 Elm St，电话是 +1 555 123 4567。”
• “为 cus_123 草拟一份优选／更优／最佳方案报价：更换热水器，价格分别为 $2,400 / $3,100 / $3,900。”
• “在 job_123 上为 Mike 预约周二上午 8-10 点。”
• “把这次上门改到周四上午，改由 Dave 负责。”
• “派 Mike 和 Dave 去处理 job_123。”
• “一次性重新定价 job_123 上的所有人工项目。”
• “客户选择了该报价的中间方案——将其标记为已批准。”
• “我们的工作时间是什么？下周什么时候有空？”
• “将作业的默认时长设为 90 分钟，到达时间窗口设为 2 小时。”

获取 Housecall Pro API 密钥

1. 以管理员身份登录 Housecall Pro。办公室员工账号无法生成密钥。
2. 打开顶部栏中的网格图标 My Apps
3. 点击 Go to App store，搜索 API，然后打开 API Key Management。它通常不会直接出现在 My Apps 菜单中，因为该菜单只列出部分应用，而非整个目录。
4. 点击 Generate new API key，为密钥命名并选择其访问级别：
   • 只读，用于报表、查询和导出。它会拒绝整个账户中的写入操作，但我们测得有一个例外：/api/price_book/ 下的价格手册路由不受此限制，只读密钥仍可在其中创建和删除价格手册类别。如果你想要绝对保证，而不是几乎保证，请使用 --read-only 运行此服务；该选项不会注册任何写入工具。
   • 完全访问权限，还允许创建客户、作业和估价单。
5. 复制密钥。Housecall Pro 之后仍会在该页面显示密钥，因此你可以返回并再次复制。但你无法编辑密钥：要更改访问级别，必须生成新密钥并删除旧密钥。

带截图的操作指南见 https://hcpapi.com/mcp/#key。

你选择的访问级别就是实际的边界。此服务会遵循你生成的密钥权限，因此只读密钥根本无法访问写入工具。如果你只想让助手回答问题，请生成只读密钥，由 Housecall Pro 为你强制执行此限制。

只有管理员可以生成密钥，而管理员拥有整个账户的完全访问权限，因此该密钥可以访问整个账户，而非仅限某个人的部分数据。

工具

共有 96 个工具。任何密钥都可用于读取；写入则需要完全访问权限的密钥。工具按工具集分组，因此安装时只需注册所需的分组——请参阅选择要注册的工具。

阅读

工具	功能
hcp_get_company	公司资料，包括账户时区和默认到达时间段
hcp_get_schedule_availability	账户的工作时间，以及可提前多久预约
hcp_list_booking_windows	Housecall Pro 报告的可预约时段，以及其中哪些时段空闲
hcp_search_customers	搜索或列出客户，或按标签筛选
hcp_get_customer	单个客户的完整记录
hcp_contactability	客户是否适合联系——汇总 API 可读取的所有禁止联系信号，并指出无法读取的那一项
hcp_list_jobs	按状态、排期时段或客户列出工作
hcp_get_job	单项工作的完整记录
hcp_get_job_notes · hcp_get_job_count	工作备注，以及账户的工作总数
hcp_list_job_appointments	工作已预约的上门服务、时段和技术人员
hcp_get_job_line_items	单项工作的明细，价格以美元计
hcp_get_job_input_materials	工作中实际使用的材料，与开具账单的材料有所区别
hcp_list_checklists	附加到工作或估价单的检查清单
hcp_list_invoices	指定日期范围内的发票，可按状态（paid、open、canceled）筛选
hcp_get_invoice	单张发票的完整信息，包括付款、退款和余额
hcp_get_job_invoices	单项工作的发票，无需遍历整个列表
hcp_get_invoice_document	客户看到的发票页面预览
hcp_list_estimates	估价单及其选项、审批日期和指定员工
hcp_get_estimate	单张估价单的完整信息
hcp_get_estimate_line_items	估价单选项中的明细
hcp_list_leads · hcp_get_lead	尚未转化的咨询，以及包含明细的单条线索
hcp_list_events · hcp_get_event	非工作类日历条目，包括重复规则和参与者
hcp_get_customer_address	按 ID 查询单个地址，适用于你有地址 ID、但没有客户信息的情况
hcp_get_application	账户上注册的 API 应用（如有）
hcp_list_routes	指定日期的路线：按员工分组并列出分配给他们的工作
hcp_list_service_zones	服务区域及邮政编码、出行费用，并显示某邮政编码是否在覆盖范围内
hcp_list_pipeline_statuses	为工作、线索或估价单配置的工作流阶段
hcp_search_pricebook	服务、材料、类别和价格表
hcp_list_price_forms	可预约的服务模板，包括时长和预约问题
hcp_list_employees	员工和角色
hcp_list_tags · hcp_list_job_types · hcp_list_lead_sources	账户查询项
hcp_revenue_summary	按月或明细项统计的开票收入
hcp_render_report	将调查结果生成一份交互式报告：可排序表格、可选行和打印功能。在支持此功能的客户端中于对话内打开，其他情况下则返回自包含的 HTML 文件。不调用 API
hcp_export_csv	导出客户、工作、发票或估价单的 CSV 文件
hcp_api_notes	API 对特定主题的实际处理方式，以及与文档描述的差异。答案来自汇总表，因此不会发出请求

写入

需要具有完全访问权限的密钥。

工具	功能
hcp_create_customer · hcp_update_customer	创建客户，或修改客户字段
hcp_create_customer_address	为客户添加服务地址
hcp_create_job	创建尚未安排的工单
hcp_add_job_line_items	为工单添加明细项
hcp_update_job_line_item · hcp_delete_job_line_item	修改工单中的一项明细，或将其移除
hcp_update_job_line_items	在一次调用中修改工单中的多项明细
hcp_add_job_note · hcp_delete_job_note	添加内部备注，或移除备注。删除后会重新读取工单以确认
hcp_upload_job_attachment	将照片或文档作为 base64 附加到工单。会根据工单的附件列表确认。没有公开接口可移除附件
hcp_upload_estimate_option_attachment	对估价选项执行相同操作。无法读取确认，因此请保留返回的 id
hcp_schedule_estimate_option	为估价选项预约上门，并派遣人员前往。notify 默认值为 false；Housecall Pro 仍可能在临近日期时提醒客户
hcp_add_job_link · hcp_add_estimate_option_link	附加带标题的链接。账户必须有应用，否则会返回“Application not found”
hcp_lock_job · hcp_lock_jobs_by_date	冻结工单，或冻结从某个日期起的所有工单。此 API 无法解锁，需通过控制面板操作，因此请先询问
hcp_set_application_enabled	启用或停用账户的 API 应用。会影响账户上的所有集成
hcp_create_webhook_subscription · hcp_delete_webhook_subscription	订阅或取消订阅投递 URL。此功能仅对合作伙伴开放；端点返回一次 5xx 后，订阅就会被移除
hcp_update_job_input_materials	替换工单中记录的现场用料。此操作会替换整个列表，因此请先读取
hcp_add_job_tag · hcp_remove_job_tag	为工单添加标签，或将其移除
hcp_schedule_job_appointment	为工单预约上门并派遣技术人员，从而安排工单
hcp_update_job_appointment	更改上门时间、派遣人员，或同时更改两者
hcp_delete_job_appointment	移除工单的一次上门安排
hcp_unschedule_job	清除工单的上门安排和日程，将其恢复为待安排状态
hcp_dispatch_job	为工单安排施工团队。客户会看到此操作，因此应视为会联系到客户
hcp_create_estimate · hcp_add_estimate_option	创建包含多个选项的估价草稿，或为其添加选项
hcp_approve_estimate_options · hcp_decline_estimate_options	记录客户对一个或多个估价选项的答复
hcp_update_estimate_option_line_items	替换估价选项中的明细项。此操作会替换整个列表
hcp_add_estimate_option_note · hcp_delete_estimate_option_note	为估价选项添加备注。无法读取确认，因此请保留 id
hcp_create_lead	创建潜在客户
hcp_convert_lead	将潜在客户转为估价单或工单。潜在客户记录仍会保留
hcp_create_tag · hcp_rename_tag	创建标签，或重命名标签
hcp_create_job_type · hcp_rename_job_type	创建工单类型，或重命名工单类型。删除需通过控制面板操作
hcp_create_lead_source · hcp_rename_lead_source	创建或重命名潜在客户来源，这是 lead_source 的有效值列表
hcp_create_pricebook_material · hcp_update_pricebook_material · hcp_delete_pricebook_material	添加、更改或移除价目表材料
hcp_create_pricebook_material_category · hcp_update_pricebook_material_category · hcp_delete_pricebook_material_category	添加、重命名或移除价目表材料类别
hcp_create_price_form · hcp_update_price_form · hcp_delete_price_form	添加、更改或移除可预约服务模板

商店默认值

工具	功能说明
hcp_get_defaults	读取此安装实例存储的默认值
hcp_set_defaults	存储一项或多项默认值，或传入 null 清除某项
hcp_get_business_profile	读取业务档案：商店信息、供应商、定价、薪资和消息规则
hcp_set_business_profile	存储一个或多个档案部分，或传入 null 清除某部分

系统会保留三项偏好设置：未另行说明时安排工作的时长、默认的到达时间窗口，以及大多数工作采用的行项目名称。这样就不必重复回答同一个问题。

这些设置存储在由服务自行管理的文件中。如果设置了 HCP_MCP_DEFAULTS_PATH，则该变量会直接指定文件路径；否则，Windows 上的路径为 %APPDATA%\housecall-pro-mcp\defaults.json，其他系统上则为 $XDG_CONFIG_HOME/housecall-pro-mcp/defaults.json；如果未设置该变量，则回退到主目录下的 .config/housecall-pro-mcp/defaults.json。此位置按计算机区分，而非按 Housecall Pro 账户区分：该文件属于已安装的服务，因此商店在两台计算机上运行服务时，需要分别在每台计算机上设置默认值。文件中的任何内容都不会发送给 Housecall Pro，而且服务只接受一组固定的键，因此不能在其中存放任何客户或工作信息。

业务档案是功能更全面的同类配置，专为运行设置访谈的技能设计：包含五个部分——shop、vendors、pricing、payroll、comms，涵盖商店信息、采购对象及其文件的接收方式、利润率和舍入规则、薪资周和佣金规则，以及外发消息的语气。技能会在提出设置问题前读取档案，以免重复提问；每个部分都会记录上次确认的日期，而且每次都会完整替换整个部分，因此技能只有在读回该部分并获得确认后才会保存。文件约定与默认值相同（可通过 HCP_MCP_PROFILE_PATH 覆盖，profile.json 与 defaults.json 存放在同一目录），隐私保护措施也相同：按计算机区分、绝不传输、仅接受固定的部分集合、不包含任何客户信息；对于看起来像完整账号的供应商 account_hint，系统会拒绝接受。

构建桌面捆绑包

manifest.json 将此服务描述为一个 MCP 捆绑包，可通过拖放安装到桌面客户端，无需安装 Node，也无需编辑配置文件。

npx -y @anthropic-ai/mcpb pack .

这会生成 housecall-pro-mcp-<version>.mcpb。.mcpbignore 会将构建时依赖排除在外；如果没有这些规则，捆绑包就会包含 TypeScript 编译器，体积接近原来的三倍。捆绑包会在客户端自己的设置界面中提示用户输入 API 密钥，并可选择设置只读模式和工具集列表，而不是通过文件进行配置。

选择要注册的工具

服务器注册的每个工具，客户端都必须在执行任何工作前将其纳入上下文；工具列表越长，客户端在选择重要工具时就越容易出错。因此，工具集是可选的。

# Only what a reporting session needs, and nothing that can change anything
npx -y housecall-pro-mcp --read-only --toolsets=reports,invoices,customers

# A group, plus the one tool from elsewhere this session actually needs
npx -y housecall-pro-mcp --toolsets=reports --tools=hcp_list_jobs

# Exactly these two tools and nothing else
npx -y housecall-pro-mcp --toolsets=none --tools=hcp_list_jobs,hcp_get_company

选项	效果
--read-only	不注册任何可以更改内容的工具。也可使用 HCP_READ_ONLY=1
--toolsets=a,b	仅注册这些组。也可使用 HCP_TOOLSETS
--tools=a,b	按名称额外注册这些单独的工具。也可使用 HCP_TOOLS
--help	列出各组并退出

组包括：company、customers、jobs、estimates、invoices、pricebook、schedule、reports、admin。此外，all 表示全部，default 表示默认集合，none 表示不包含任何组。

--tools 会在 --toolsets 的基础上追加工具，因此你可以添加某个组不包含的单个工具，而无需引入整个组。不带 --toolsets 指定工具名称时，只会提供这些工具，不包含其他内容。如果名称不是实际存在的工具，服务器会停止，并显示最接近的名称，而不会在悄无声息地缺少你所需工具的情况下启动。--read-only 的优先级仍然最高：指定写入工具也不会注册它。

admin 组用于标记、作业类型和价目表结构的维护——也就是重塑这些注册表的写入操作。它不属于默认集合，因为预约或报告会话从不需要它；将其排除也能缩小初始工具集。需要时，请按名称指定，或使用 --toolsets=default,admin。列出标记和作业类型不属于 admin：这些读取操作有助于解读常规作业数据，因此始终包含在默认集合中。

如果组名称拼写错误，服务器会停止，并显示有效名称，而不是在缺少工具的情况下启动。如果安装后悄无声息地没有提供任何工具，表现就会和 API 无法访问完全一样。

--read-only 与密钥的访问级别是两回事。只读密钥本身就会在 API 层拒绝写入。此选项则会完全不注册写入工具；当你让 Agent 查看真实账户时，这正是你需要的——写入工具不只是受到限制，而是根本不存在。

如果没有 HCP_API_KEY，服务器仍会以无密钥模式启动：只注册从不调用 Housecall Pro 的工具——hcp_render_report、hcp_api_notes 和一对 business-profile 工具——且没有任何工具能够访问 Housecall Pro 账户。这样一来，你可以在使用仪表板 CSV 导出文件而非 API 时继续使用报告渲染器，也可以在密钥尚不存在时运行技能的设置访谈。

服务器会预先告知模型什么

本项目的两张表会编译进服务器，而不是留在此 README 中，因为 README 是给人看的，不会被模型读取。

• 连接时指令包含防止最严重故障的规则：Housecall Pro 写入操作即使返回 2xx，也绝不能轻信；必须重新读取记录。
• hcp_api_notes 会根据上面两个章节所依据的同一份已验证表格，用通俗语言回答有关 API 实际行为的问题——无论是路由、字段，还是你尝试执行的操作。它不会发出请求，因此不产生任何开销。在断定某事无法完成之前，以及任何写入操作报告成功却看起来毫无变化之后，都应先询问它。
• 对于可以读取资源而无需消耗工具调用的客户端，同样的表格也会以 MCP 资源的形式提供（hcp://api-notes/quirks 和 hcp://api-notes/phantom-routes）。

工作方式

写入工具只能使用完整访问权限的密钥。如果使用只读密钥调用其中任何一个，操作都会失败，并显示明确说明原因的消息，而不会执行意料之外的操作。

每个工具都带有规范中的注释，因此客户端无需从名称推断，就能区分读取和写入、写入和删除操作，也能判断某项操作是否会触达客户。hcp_dispatch_job 以及估价单的批准和拒绝工具都标记为可能会通知客户，因为它们确实会通知客户。 每个工具都会以结构化数据和文本形式返回结果，因此需要记录的客户端无需从文字说明中解析出来。工具列表还会声明输出架构，这意味着在调用任何工具之前，就能从 tools/list 中读取字段名称、类型和嵌套结构。对于原样返回 Housecall Pro 记录的工具，我们会有意不声明架构：描述我们无法控制的字段，一旦过时也不会有人察觉。

这里没有任何工具会替你发送电子邮件、短信或报价单。拟定报价单后，它会保持为草稿；是否发送，仍由你在 Housecall Pro 中主动决定。

报告会在你正在阅读的地方打开。对于支持 MCP Apps 的客户端（目前为 Claude 和 Claude Desktop，不包括 Claude Code），hcp_render_report 会直接在对话中呈现报告：同一份可排序、可筛选的报告，其行仍可选中并带回聊天中。不会下载任何内容，也不会写入任何文件。其他情况下，该工具会像以前一样将报告作为一个独立完整的 HTML 文件返回，因此不依赖此功能是否可用。无论哪种形式，报告都不会发起网络请求，因此也能在这些客户端采用的严格内容策略下运行。如果你的客户端声称支持此功能，但你仍然看不到报告，请再次请求报告并使用 as_file，即可取回文件版本。

派遣团队会让客户看到。 hcp_dispatch_job 会为工作安排技术人员，而客户可以看到这项安排：Housecall Pro 可能会告知客户由谁上门，以及有人正在赶来。无论它是否发送了通知，我们都没有监测过，因此请将其视为会联系客户，而不要假定它不会。

在报价单选项上记录客户的答复，是商家记下客户所说的话，并非发出询问。Housecall Pro 对结果的说法是“pro approved”或“pro declined”，这正是 hcp_approve_estimate_options 和 hcp_decline_estimate_options 所记录的内容。实际测试时，这些操作没有发送电子邮件或短信。这并不代表你的账户也一定如此：Housecall Pro 的自动化和通知设置会自行发送通知，与任何单次调用无关；一个账户的配置也不能说明另一个账户的情况。如果某个账户设置为将已批准的选项复制到工作中，那么批准选项时就会创建一项工作，并在响应中给出该项工作。

更改多个明细项只需调用一次。 hcp_update_job_line_items 会在单个请求中将完整列表交给 Housecall Pro。hcp_update_job_line_item 则每行发送一个请求，因此连续调用时可能中途停止，导致工作的部分项目已重新定价；只有一行需要更改时才使用它，多行需要更改时请使用批量工具。

预约一项工作只需调用一次。 在工作中创建预约也会设置该工作的日程，因此 hcp_schedule_job_appointment 会同时预约工作并派遣人员：该工作不再显示为需要排期，访问也会安排给你指定的技术人员。若要添加第二次上门，请在同一工作上再次调用。每个预约都至少需要一名技术人员；如果未指定任何人，此处会拒绝预约，而不会发送请求。

使用 hcp_update_job_appointment 更改上门时间时，也会同步更改工作的日程，因此重新排期同样只需调用一次。取消预约时，单次上门请使用 hcp_delete_job_appointment；若要移除所有上门安排并将整项工作恢复为需要排期，请使用 hcp_unschedule_job。

在向客户提供时间之前，hcp_get_schedule_availability 会提供账户的营业时间，而 hcp_list_booking_windows 会提供系统报告为可预约的时段，这样你提供的时间就会与账户的实际安排相符。

这些调用本身都不会向客户发送电子邮件或短信。Housecall Pro 会在日期临近时发送自己的预约提醒，具体取决于你的账户设置，而非此服务。你在 Housecall Pro 中设置的自动化会独立运行，不受此服务控制。 写入失败后不会自动重试，因此网络短暂中断不会悄悄创建重复记录。

你的 API 密钥只会发送到 api.housecallpro.com。此 MCP 服务发出的唯一其他请求是“更新”部分所述的版本检查，该请求不携带任何账户数据。

密钥的去向

配置的密钥只有一个，且只会发送到一个主机。

• 你的 Housecall Pro API 密钥（HCP_API_KEY）只会发送到 api.housecallpro.com。从你的 Housecall Pro 账户读取的任何内容都不会发送到其他地方。

此 MCP 服务发出的唯一其他请求是“更新”部分所述的版本检查，该请求会携带产品名称和已安装版本，不包含其他内容。

限制

还有一些限制属于设计上的边界，并非异常行为。

预约属于某个工单。 没有面向整个账户的预约列表，因此你需要逐个工单查看上门服务。请查询某个工单的预约，而不是查询“本周的所有预约”。不过，账户自身的日程安排是面向整个账户的：hcp_get_schedule_availability 会返回其工作时段，hcp_list_booking_windows 会返回其报告为可预约的时段。

到达时间窗口必须是 Housecall Pro 接受的时长： 0、15、20、60、120、180 或 240 分钟，其中 0 表示精确时间。写入时，系统会拒绝其他任何数值，因此预约工具会提供可接受时长列表，而不是允许输入任意数字。

预约可以撤销；工单无法删除。 hcp_unschedule_job 会移除上门服务并清空日程，将工单保留在“待安排”状态，同时保留其客户、明细项目和备注。Housecall Pro 的 API 没有删除工单的接口，因此，如果误建了工单，需要直接在 Housecall Pro 中将其关闭。

客户地址只能追加。 hcp_create_customer_address 会添加一个地址，之后没有接口可以修改或移除它。添加前请确认地址无误；如果地址有误，需要在 Housecall Pro 中更正。

每次只能移除工单上的一个标签。 hcp_remove_job_tag 需要工单和标签；没有一次性清除工单上所有标签的调用。该操作还需要具备标签更改权限的密钥，因此此处出现 401 表示密钥的访问级别不足，而非缺少功能。

必须按工单或估价单查询检查清单。 无法列出账户上的所有检查清单；如果返回空结果，表示这些记录尚未设置检查清单，而不是操作出了问题。

标签可以创建和重命名，但不能删除。 删除账户中的标签需要在 Housecall Pro 中操作。请谨慎创建标签。

更新

启动时，MCP 服务会检查 hcpapi.com 是否有更新版本；该请求会携带产品名称和已安装版本，不包含其他内容。如果有更新版本，下一次工具响应中会提示一次。如果检查无法完成，MCP 服务会继续运行。

要更新，请重新运行客户端的安装命令；“安装”部分中的 npx 配置会拉取最新发布版本。如果客户端仍在使用较旧的缓存副本，请将参数改为 ["-y", "housecall-pro-mcp@latest"]，以强制使用最新版本。

故障排除

401 Unauthorized。 密钥可能是只读的，而你调用了写入工具；也可能是创建密钥的员工没有相应数据的访问权限。请生成一个拥有完整访问权限的密钥，或检查该员工的权限。

预期有数据，但结果为空。 通常也是上述原因。员工范围的密钥只能返回该员工有权查看的内容。

客户端中没有显示任何工具。 请使用 node --version 检查 Node 版本是否为 18 或更高版本，并确认 HCP_API_KEY 已设置在 MCP 服务的 env 块中，而不是设置在 shell 中。

进一步了解

此 MCP 服务涵盖 Housecall Pro API 本身。我们正在构建其上层功能：报告和导出工作流、价格簿工具，以及 webhook 设置。如果你对此感兴趣，请发送邮件至 [email protected]，我们会在功能就绪时通知你。

问题和拉取请求

欢迎在问题跟踪器中提交错误报告和功能请求，越多越好。请说明你让助手做了什么，以及助手返回了什么。

拉取请求会自动关闭。发布版本会通过一套内部测试进行验证，而拉取请求无法运行这套测试，因此我们无法在这里诚实地审查拉取请求。在问题跟踪器中告诉我们哪里出了问题，比提交补丁能更快地解决问题。

许可证

MIT，版权归 HCP API 所有。本项目独立运营，与 Housecall Pro 无关联。“Housecall Pro” 是其所有者的商标，此处仅用于说明兼容性。