AI导哈

Housecall Pro MCP服务

Housecall Pro MCP是一个独立的模型上下文协议服务器，用于管理客户、工作、工作流、估计、发票、潜在客户等业务功能。

  • by blake7ferrin
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 blake7ferrin/Housecall-Pro-MCP

使用说明

Housecall Pro MCP

这是Housecall Pro的独立模型上下文协议服务器。

它做什么

  • 客户：列表、获取、创建、更新、列出地址、获取地址、创建地址
  • 工作：列表、获取、创建、更新/清除日程、调度、创建约会、锁定（单个或批量）、添加/删除笔记、添加/移除标签、创建链接、列出材料
  • 工作流程：查找或创建客户、预订任务、安排和调度、将潜在客户转换为任务、获取所有页面
  • MCP资源：公司、员工、工作类型、潜在客户来源、标签、管道状态、价格手册服务、API惯例、webhook事件
  • MCP提示：早间调度简报、预估跟进、发票账龄分析、预订服务电话
  • 估算：列出、获取、创建、批准/拒绝选项、管理选项（创建、行项目、计划、注释、链接）
  • 发票：列表、按UUID获取、作业列表
  • 潜在客户：列出、获取、创建、转换、列出潜在客户项目
  • 应用程序：获取、启用、禁用
  • 公司和日程安排：获取公司、获取/更新日程窗口、获取预订窗口
  • 元数据：员工、清单、事件、标签、潜在客户来源、工作类型、服务区域、路线、管道状态
  • 价格簿：列出/创建/更新/删除物料、物料类别和价格表单；列出服务

为什么路由是可配置的

Housecall Pro的官方公开API文档发布在 docs.housecallpro.com，并且当前身份验证页面声明API同时支持API密钥和OAuth 2.0。文档是JS繁重的，因此这个脚手架通过环境变量保持基本URL、认证方案和路由模板的可配置性。

此项目中的当前默认值为：

  • https://api.housecallpro.com
  • HOUSECALL_PRO_AUTH_SCHEME=auto
  • /customers
  • /customers/{customerId}
  • /jobs
  • /jobs/{jobId}
  • /estimates
  • /estimates/{estimateId}
  • /invoices
  • /invoices/{invoiceId}
  • /jobs/{jobId}/invoices
  • /leads

如果您的租户使用不同的身份验证标头或不同的路径，请更新 .env.

设置

  1. 复制 .env.example 到 .env.
  2. 集 HOUSECALL_PRO_API_KEY 或 HOUSECALL_PRO_BEARER_TOKEN.
  3. 对于多位置帐户，可选择设置 HOUSECALL_PRO_COMPANY_ID 通过以下方式确定请求范围 X-Company-Id 头球
  4. 对于OAuth集成，设置 HOUSECALL_PRO_BEARER_TOKEN 加上 HOUSECALL_PRO_OAUTH_* 变量，以在401响应上启用自动令牌刷新。
  5. 如果需要，设置 HOUSECALL_PRO_AUTH_SCHEME 到 auto, bearer, token, x-api-key，或 authorization.
  6. 安装依赖项。
  7. 构建服务器。
npm install
npm run build

跑

npm start

在铁路上部署（公共URL）

此项目可以作为 公共HTTP MCP服务器 （流式HTTP）用于需要HTTP端点（如Slack机器人）的集成。

环境变量

您必须设置以下之一：

  • HOUSECALL_PRO_API_KEY
  • HOUSECALL_PRO_BEARER_TOKEN

可选（推荐）：

  • MCP_HTTP_BEARER_TOKEN （保护公众 /mcp 端点）
  • HOUSECALL_PRO_COMPANY_ID （将API请求范围定为特定子位置）
  • HOUSECALL_PRO_OAUTH_CLIENT_ID, HOUSECALL_PRO_OAUTH_CLIENT_SECRET, HOUSECALL_PRO_OAUTH_REFRESH_TOKEN, HOUSECALL_PRO_OAUTH_REDIRECT_URI （自动刷新OAuth令牌）
  • HOUSECALL_PRO_RATE_LIMIT_MAX_RETRIES （默认情况下，在HTTP 429上重试 3)

铁路CLI

npm i -g @railway/cli
railway login
railway init

# Required Housecall Pro auth
railway variables set HOUSECALL_PRO_API_KEY="..."

# Recommended: protect your public MCP endpoint
railway variables set MCP_HTTP_BEARER_TOKEN="some-long-random-string"

railway up
railway open

端点

  • GET /healthz 返回200 OK。
  • POST /mcp, GET /mcp, DELETE /mcp 实现MCP流式HTTP。
    • 如果 MCP_HTTP_BEARER_TOKEN 已设置，发送 Authorization: Bearer <token>.

对于当地发展：

npm run dev

要验证真实帐户的身份验证和默认路由：

npm run smoke

MCP客户端示例

{
  "mcpServers": {
    "housecall-pro": {
      "command": "node",
      "args": ["C:/Users/blake/OneDrive/Codex/housecall-pro-mcp/dist/index.js"],
      "env": {
        "HOUSECALL_PRO_API_KEY": "replace-me",
        "HOUSECALL_PRO_AUTH_SCHEME": "auto",
        "HOUSECALL_PRO_BASE_URL": "https://api.housecallpro.com"
      }
    }
  }
}

备注

  • Housecall Pro的帮助中心表示，MAX客户可以使用API访问和webhook。
  • 此项目已根据客户、工作、估算、发票、公司、员工、潜在客户来源、工作类型、标签、服务区域、路线和管道状态读取路线进行了实时验证 https://api.housecallpro.com.
  • 在 auto 客户端使用的模式 Authorization: Token ... 对于API密钥和 Authorization: Bearer ... 对于OAuth令牌，与Housecall Pro发布的身份验证指南相匹配。
  • 当配置OAuth刷新凭据时，客户端会自动刷新401上过期的承载令牌，并重试一次请求。
  • 客户端以指数回退重试速率受限的请求（HTTP 429）。
  • MCP资源在以下位置公开参考数据 housecall://reference/* 公司元数据、目录和静态API约定的URI。
  • MCP提示为调度简报、估算跟进、发票账龄和预订服务电话提供了现成的工作流程。
  • 您当前的凭据可以读取大多数公司级资源，但是 GET /application 并编写如下路线 POST /customers, POST /jobs，以及 POST /estimates 返回 401 Unauthorized ... does not have the necessary permissions.
  • Webhook订阅工具使用 POST /webhook_subscriptions 和 DELETE /webhook_subscriptions/{subscription_id}.
  • POST /jobs/lock 需要a statuses 阵列(scheduled, in_progress，或 completed)截至2026年6月。

相关 MCP