mcpengine/servers/housecall-pro

Housecall Pro MCP Server

Complete Model Context Protocol server for Housecall Pro field service management platform.

Features

🛠️ 47 Tools Across 10 Categories

Job Management (10 tools)

• list_jobs - List jobs with filters (status, customer, dates, tags)
• get_job - Get detailed job information
• create_job - Create new jobs
• update_job - Update job details
• complete_job - Mark jobs as completed
• cancel_job - Cancel jobs with reason
• list_job_line_items - List line items for a job
• add_job_line_item - Add line items to jobs
• schedule_job - Schedule jobs
• reschedule_job - Reschedule existing jobs

Customer Management (7 tools)

• list_customers - List customers with filters
• get_customer - Get customer details
• create_customer - Create new customers
• update_customer - Update customer information
• delete_customer - Delete customers
• search_customers - Search by name, email, phone
• list_customer_addresses - List customer addresses

Estimate Management (8 tools)

• list_estimates - List estimates with filters
• get_estimate - Get estimate details
• create_estimate - Create new estimates
• update_estimate - Update estimate details
• send_estimate - Send estimates to customers
• approve_estimate - Mark estimates as approved
• decline_estimate - Decline estimates
• convert_estimate_to_job - Convert approved estimates to jobs

Invoice Management (6 tools)

• list_invoices - List invoices with filters
• get_invoice - Get invoice details
• create_invoice - Create new invoices
• send_invoice - Send invoices to customers
• mark_invoice_paid - Record invoice payments
• list_invoice_payments - List all payments for an invoice

Employee Management (6 tools)

• list_employees - List employees with filters
• get_employee - Get employee details
• create_employee - Create new employees
• update_employee - Update employee information
• get_employee_schedule - Get employee schedules
• list_employee_time_entries - List time entries

Dispatch & Scheduling (3 tools)

• get_dispatch_board - Get dispatch board view
• assign_employee_to_job - Assign employees to jobs
• get_employee_availability - Check employee availability

Tag Management (5 tools)

• list_tags - List all tags
• create_tag - Create new tags
• delete_tag - Delete tags
• add_tag_to_job - Tag jobs
• add_tag_to_customer - Tag customers

Notification Management (3 tools)

• list_notifications - List sent notifications
• send_notification - Send SMS/email notifications
• mark_notification_read - Mark notifications as read

Review Management (3 tools)

• list_reviews - List customer reviews
• get_review - Get review details
• request_review - Request reviews from customers

Reporting & Analytics (3 tools)

• get_revenue_report - Revenue analytics
• get_job_completion_report - Job completion metrics
• get_employee_performance_report - Employee performance stats

Installation

npm install @mcpengine/housecall-pro

Configuration

Set the required environment variable:

export HOUSECALL_PRO_API_KEY="your-api-key-here"

Optional configuration:

export HOUSECALL_PRO_BASE_URL="https://api.housecallpro.com"  # default

Usage

As MCP Server

Add to your MCP settings file:

{
  "mcpServers": {
    "housecall-pro": {
      "command": "npx",
      "args": ["-y", "@mcpengine/housecall-pro"],
      "env": {
        "HOUSECALL_PRO_API_KEY": "your-api-key-here"
      }
    }
  }
}

Programmatic Usage

import { HousecallProClient } from '@mcpengine/housecall-pro';

const client = new HousecallProClient({
  apiKey: process.env.HOUSECALL_PRO_API_KEY!,
});

// List jobs
const jobs = await client.listJobs({
  work_status: 'scheduled',
  start_date: '2024-01-01',
  end_date: '2024-01-31',
});

// Create a customer
const customer = await client.createCustomer({
  first_name: 'John',
  last_name: 'Doe',
  email: 'john@example.com',
  mobile_number: '+1234567890',
});

// Create an estimate
const estimate = await client.createEstimate({
  customer_id: customer.id,
  line_items: [
    {
      name: 'HVAC Repair',
      description: 'Replace thermostat',
      quantity: 1,
      unit_price: 250.00,
    },
  ],
});

// Send the estimate
await client.sendEstimate(estimate.id);

API Reference

Client Initialization

const client = new HousecallProClient({
  apiKey: string;           // Required: Your Housecall Pro API key
  baseUrl?: string;         // Optional: API base URL (default: https://api.housecallpro.com)
});

Error Handling

The client throws APIError objects with the following structure:

{
  error: 'APIError' | 'NetworkError' | 'ExecutionError';
  message: string;
  status: number;
  details?: any;
}

Example error handling:

try {
  const job = await client.getJob('job-123');
} catch (error: any) {
  if (error.error === 'APIError') {
    console.error(`API Error ${error.status}: ${error.message}`);
  } else {
    console.error(`Error: ${error.message}`);
  }
}

Pagination

List methods support pagination:

// Get single page
const page = await client.getPage('/jobs', {
  page: 1,
  page_size: 50,
});

// Get all pages (auto-pagination)
const allJobs = await client.listJobs({
  page_size: 100,  // Items per page
});

Tool Examples

Job Management

// Create and schedule a job
const job = await client.createJob({
  customer_id: 'cust-123',
  description: 'Annual HVAC maintenance',
  schedule_start: '2024-02-15T09:00:00Z',
  schedule_end: '2024-02-15T11:00:00Z',
  assigned_employees: ['emp-456'],
});

// Add line items
await client.addJobLineItem(job.id, {
  name: 'Filter Replacement',
  quantity: 2,
  unit_price: 45.00,
});

// Complete the job
await client.completeJob(job.id);

Customer & Address Management

// Create customer with tags
const customer = await client.createCustomer({
  first_name: 'Jane',
  last_name: 'Smith',
  email: 'jane@example.com',
  tags: ['vip', 'commercial'],
});

// Get customer addresses
const addresses = await client.listCustomerAddresses(customer.id);

Estimates & Invoices

// Create estimate
const estimate = await client.createEstimate({
  customer_id: 'cust-123',
  line_items: [
    { name: 'Labor', quantity: 2, unit_price: 85.00 },
    { name: 'Parts', quantity: 1, unit_price: 150.00 },
  ],
  valid_until: '2024-03-01',
});

// Send and track
await client.sendEstimate(estimate.id);
await client.approveEstimate(estimate.id);
const job = await client.convertEstimateToJob(estimate.id);

// Create invoice from job
const invoice = await client.createInvoice({
  job_id: job.id,
  due_date: '2024-02-28',
});

// Record payment
await client.markInvoicePaid(invoice.id, {
  amount: 320.00,
  method: 'card',
  reference: 'ch_1234567890',
});

Dispatch & Scheduling

// Check employee availability
const availability = await client.getEmployeeAvailability('emp-123', {
  start_date: '2024-02-15',
  end_date: '2024-02-21',
});

// View dispatch board
const board = await client.getDispatchBoard({
  date: '2024-02-15',
  employee_ids: ['emp-123', 'emp-456'],
});

// Assign employee
await client.assignEmployee('job-789', 'emp-123');

Reports & Analytics

// Revenue report
const revenue = await client.getRevenueReport({
  start_date: '2024-01-01',
  end_date: '2024-01-31',
  group_by: 'day',
});

// Job completion metrics
const completion = await client.getJobCompletionReport({
  start_date: '2024-01-01',
  end_date: '2024-01-31',
});

// Employee performance
const performance = await client.getEmployeePerformanceReport({
  employee_id: 'emp-123',
  start_date: '2024-01-01',
  end_date: '2024-01-31',
});

MCP Apps (UI Components)

This server includes 16 React-based MCP apps for rich UI interactions:

• job-dashboard - Overview of all jobs
• job-detail - Detailed job view
• job-grid - Grid view of jobs
• customer-detail - Customer profile view
• customer-grid - Customer list/grid
• estimate-builder - Interactive estimate creation
• estimate-grid - Estimate list/grid
• invoice-dashboard - Invoice overview
• invoice-detail - Detailed invoice view
• dispatch-board - Visual dispatch/scheduling board
• employee-schedule - Employee schedule calendar
• employee-performance - Performance metrics dashboard
• review-dashboard - Review management
• revenue-dashboard - Revenue analytics
• tag-manager - Tag organization
• notification-center - Notification management

Development

# Install dependencies
npm install

# Build
npm run build

# Development (watch mode)
npm run dev

# Run server
npm start

API Documentation

For complete API documentation, visit: https://docs.housecallpro.com/

License

MIT

Support

For issues and feature requests, please visit: https://github.com/mcpengine/housecall-pro-mcp