🏠 Housecall Pro MCP 服务器

一套全面的 模型上下文协议 (MCP) 服务器 集合，用于 Housecall Pro API，使 Claude Desktop 和其他具有 MCP 能力的大型语言模型能够无缝地与您的 Housecall Pro 现场服务管理系统交互。每个服务器都专门针对特定领域，提供对客户、任务、调度、发票、材料等模块化的访问。

🚀 概述

本项目提供了 20 多个专业 MCP 服务器，通过 Claude Desktop 或其他大型语言模型暴露完整的 Housecall Pro API。无论您是在管理客户、安排任务、处理发票还是跟踪材料，这些服务器都能为您提供强大的人工智能辅助访问您的现场服务操作。

🏗️ 架构

每个 Housecall Pro API 域都有自己的专用 MCP 服务器，以实现专注和高效的运营：

📋 核心业务操作

• housecallpro_customers.py - 客户及地址管理
• housecallpro_jobs.py - 任务管理、调度及派遣
• housecallpro_employees.py - 员工管理及筛选
• housecallpro_appointments.py - 预约安排及状态管理

💰 财务管理

• housecallpro_invoices.py - 发票管理和支付
• housecallpro_invoices_query.py - 高级发票查询
• housecallpro_job_invoices.py - 任务特定发票操作
• housecallpro_estimates.py - 报价创建及管理

📦 库存及材料

• housecallpro_materials.py - 材料管理和定价
• housecallpro_material_categories.py - 材料类别组织
• housecallpro_price_forms.py - 价格表及表单管理

🎯 销售及营销

• housecallpro_leads.py - 领导管理及转化
• housecallpro_lead_sources.py - 领导来源追踪
• housecallpro_tags.py - 标签管理和组织

⚙️ 系统及配置

• housecallpro_company.py - 公司信息及设置
• housecallpro_job_types.py - 任务类型配置
• housecallpro_schedule.py - 调度管理
• housecallpro_events.py - 事件及日历管理
• housecallpro_webhooks.py - Webhook 配置及管理
• housecallpro_application.py - 应用程序设置及偏好
• housecallpro.py - 统一服务器，具备核心功能

🌟 关键特性

📋 客户管理 (housecallpro_customers.py)

客户操作

• 获取客户 - 列出客户并进行高级过滤（搜索、日期范围、分页）
• 根据ID获取客户 - 获取详细的客户资料
• 创建客户 - 添加新客户及其完整信息
• 更新客户 - 修改现有客户的详细信息

地址管理

• 获取客户地址 - 列出所有客户的地址
• 根据ID获取客户地址 - 获取特定地址的详细信息
• 创建客户地址 - 为客户添加服务地点

👥 员工管理 (housecallpro_employees.py)

员工操作

• 获取员工 - 列出员工，并按以下条件过滤：
  • 活动状态、角色、标签
  • 名字、电子邮件、电话搜索
  • 自定义分页和排序
• 根据ID获取员工 - 包括以下内容的详细员工资料：
  • 个人详情（联系方式、头像）
  • 就职信息（角色、入职日期、状态）
  • 权限和访问级别
  • 标签和元数据

💼 任务管理 (housecallpro_jobs.py)

核心任务操作

• 获取任务 - 使用以下过滤器进行高级任务列表：
  • 状态（已安排、进行中、已完成、已取消）
  • 客户、员工、日期范围
  • 任务编号、描述、地址搜索
  • 工作状态、业务单元、标签
• 根据ID获取任务 - 包括项目明细、调度、附件在内的完整任务详情
• 创建任务 - 创建完整任务，包括客户分配、调度、派遣

任务调度及派遣

• 更新任务调度 - 修改时间和预约
• 删除任务调度 - 删除已安排的预约
• 派遣任务给员工 - 分配技术人员和团队

项目明细管理

• 获取/添加/更新/删除任务项目明细 - 完整的项目明细操作
• 批量更新项目明细 - 高效的批量更新
• 获取/更新任务输入材料 - 材料使用跟踪

任务文档

• 添加任务附件 - 上传文件、照片、文档
• 添加/删除任务备注 - 内部沟通和跟踪
• 创建任务链接 - 外部资源管理
• 添加/移除任务标签 - 组织和分类

📅 预约管理 (housecallpro_appointments.py)

核心预约操作

• 获取预约 - 列表并按客户、员工、状态、日期过滤
• 根据ID获取预约 - 详细的预约信息
• 创建/更新/删除预约 - 完整的预约生命周期管理

调度及管理

• 重新安排预约 - 移动预约并通知客户
• 获取预约可用性 - 查找可用的调度时段
• 发送预约提醒 - 客户通信自动化

状态管理

• 标记预约到达/开始/完成 - 实时状态跟踪
• 标记预约未到 - 处理客户未到的情况

💰 发票管理 (housecallpro_invoices.py)

发票操作

• 获取发票 - 使用状态、客户、日期、付款状态进行高级过滤
• 根据ID获取发票 - 包含项目明细和附件的完整发票详情
• 创建发票 - 从任务生成带有自定义条款的发票
• 更新发票 - 修改金额、到期日、条款、消息

支付及处理

• 发送发票 - 通过电子邮件/短信发送并附带自定义消息
• 标记发票已付 - 记录多种方式的付款
• 作废发票 - 取消发票并记录原因
• 获取发票付款 - 支付历史和跟踪

项目明细管理

• 添加/更新/删除发票项目明细 - 详细的发票组成
• 获取发票附件 - 支持文档
• 下载发票PDF - 生成格式化的发票

📦 材料管理 (housecallpro_materials.py)

材料操作

• 获取材料 - 按类别列出材料并进行过滤
• 获取材料类别 - 层次化类别浏览
• 按名称查找类别 - 搜索类别结构
• 创建/更新/删除材料 - 完整的材料生命周期

💡 报价管理 (housecallpro_estimates.py)

报价操作

• 获取报价 - 按状态、客户、员工、日期过滤
• 根据ID获取报价 - 包含选项的完整报价详情
• 创建报价 - 生成带有多个选项的报价

报价选项管理

• 创建报价选项附件/链接 - 支持文档
• 更新报价选项时间线 - 时间线管理
• 创建/删除报价选项备注 - 内部跟踪

🎯 领导管理 (housecallpro_leads.py)

领导操作

• 获取领导 - 按来源、状态、员工、日期进行高级过滤
• 根据ID获取领导 - 完整的领导信息和历史
• 创建领导 - 捕获新潜在客户及其完整详情
• 更新领导 - 修改领导信息和状态
• 转换领导 - 将领导转化为客户

领导沟通

• 添加领导备注 - 跟踪沟通和跟进
• 删除领导备注 - 清理领导历史

🏷️ 组织及标签 (housecallpro_tags.py)

标签管理

• 获取标签 - 列出所有可用标签并进行过滤
• 根据ID获取标签 - 详细的标签信息
• 创建标签 - 添加新的组织标签
• 更新标签- 修改标签属性
• 删除标签 - 移除未使用的标签

⚙️ 系统配置

公司管理 (housecallpro_company.py)

• 获取公司信息 - 商业详情和设置

任务类型 (housecallpro_job_types.py)

• 获取任务类型 - 列出可用的服务类型及其定价

调度管理 (housecallpro_schedule.py)

• 获取调度 - 查看技术人员的调度和可用性

事件 (housecallpro_events.py)

• 获取事件 - 日历事件和调度冲突

Webhook (housecallpro_webhooks.py)

• 获取/创建/更新/删除Webhook - 实时集成管理

预备知识

• Python 3.8+
• uv 包管理器
• Housecall Pro API 密钥
• Claude Desktop 应用程序或其他 MCP LLM 客户端

设置说明

1. 安装 uv（如果尚未安装）

Windows:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

macOS/Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

2. 克隆并设置项目

git clone https://github.com/BuildWithBeacon/housecallpro-mcp.git
cd HousecallPro-mcp
uv sync

或者下载 ZIP 并解压到选择的目录。

3. 获取 Housecall Pro API 密钥

1. 登录您的 Housecall Pro 账户
2. 转到应用商店 > API 密钥管理 > 生成
3. 生成您的 API 密钥
4. 复制您的 API 密钥（确保安全！）

4. 环境设置

将 ".env.example" 更名为 ".env" 在 API 密钥后填入密钥，无空格

5. 配置 Claude Desktop

复制 claude_desktop.json 模板并粘贴到您的 AI MCP 服务器配置中。

更新 claude_desktop_config.json 中的路径：

注意：API 密钥将自动从您的 .env 文件中读取 - 不需要在 JSON 配置中包含它。

重要：如果 uv 不在您的系统 PATH 中，请将 "uv" 替换为 uv 可执行文件的完整路径（例如，在 Windows 上为 "C:\\Users\\YourUsername\\.cargo\\bin\\uv.exe"）。

Windows:

{
  "mcpServers": {
    "housecall-pro-customers": {
      "command": "uv",
      "args": [
        "--directory",
        "C:\\\\Users\\\\YourUsername\\\\path\\\\to\\\\HousecallPro-mcp",
        "run",
        "housecallpro_customers.py"
      ]
    }
  }
}

等等。从提供的模板添加所有服务器，并更改克隆的位置。

macOS/Linux:

{
  "mcpServers": {
    "housecall-pro-customers": {
      "command": "uv",
      "args": [
        "--directory",
        "/Users/yourusername/path/to/HousecallPro-mcp",
        "run",
        "housecallpro_customers.py"
      ]
    }
  }
}

等等。从提供的模板添加所有服务器，并更改克隆的位置。

6. 重启 Claude Desktop

配置完成后，重启 Claude Desktop 以加载新的 MCP 服务器。您现在应该可以在搜索和工具标签中看到可用的 MCP 服务器。

📝 使用示例

配置完成后，您可以向 Claude 提问如下问题：

• "显示所有客户"
• "获取 'name' 的客户ID"
• "创建一个名为 John Doe 的新客户"
• "列出客户 12345 的所有地址"
• "为客户 12345 添加一个新的地址"

🛠️ 故障排除

常见问题：

1. "未找到服务器"

   • 检查 claude_desktop_config.json 中的路径是否正确
   • 确保已安装并可访问 uv
   • 如果找不到 uv 命令，则：
     • 将 uv 添加到您的系统 PATH，或
     • 在配置中使用 uv 的完整路径（例如，在 Windows 上为 C:\\Users\\YourUsername\\.cargo\\bin\\uv.exe）

2. "身份验证失败"

   • 验证 .env 文件中的 API 密钥
   • 检查您的 Housecall Pro API 密钥是否具有必要的权限

3. "权限被拒绝"

   • 确保 Python 文件是可执行的
   • 检查 uv 是否具有适当的权限

🤝 贡献

1. 分叉仓库
2. 创建功能分支
3. 添加您的改进
4. 提交拉取请求

📄 许可

随便用，不追究

🔗 相关链接

• Housecall Pro API 文档
• 模型上下文协议
• Claude Desktop