Housecall Pro MCP

Housecall Pro MCP

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

它做什么

• 客户：列表、获取、创建、更新、列出地址、获取地址、创建地址
• 作业：按时间范围列出、获取、创建、锁定
• 估计：列表、获取、创建
• 发票：列表、按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
• /api/invoices/{invoiceId}
• /jobs/{jobId}/invoices
• /leads

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

设置

1. 复制 .env.example 到 .env.
2. 集 HOUSECALL_PRO_API_KEY 或 HOUSECALL_PRO_BEARER_TOKEN.
3. 如果需要，设置 HOUSECALL_PRO_AUTH_SCHEME 到 auto, bearer, token, x-api-key，或 authorization.
4. 安装依赖项。
5. 构建服务器。

npm install
npm run build

跑

npm start

在铁路上部署（公共URL）

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

环境变量

您必须设置以下之一：

• HOUSECALL_PRO_API_KEY
• HOUSECALL_PRO_BEARER_TOKEN

可选（推荐）：

• MCP_BEARER_TOKEN （保护公众 /mcp 端点）

铁路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_BEARER_TOKEN="some-long-random-string"

railway up
railway open

端点

• GET /healthz 返回200 OK。
• POST /mcp, GET /mcp, DELETE /mcp 实现MCP流式HTTP。

- 如果 MCP_BEARER_TOKEN 已设置，发送 Authorization: Bearer .

对于当地发展：

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发布的身份验证指南相匹配。
• 您当前的凭据可以读取大多数公司级资源，但是 GET /application 并编写如下路线 POST /customers, POST /jobs，以及 POST /estimates 返回 401 Unauthorized ... does not have the necessary permissions.
• Webhook订阅端点在MCP中映射，但Housecall Pro的OpenAPI规范没有详细描述请求体形状，因此这些工具接受通用的JSON有效载荷。