Jake Shore 5adccfd36e housecall-pro: Complete MCP server with 47 tools, 16 React apps, full API client

- API Client: Housecall Pro API with auth, pagination, error handling
- 47 Tools across 10 categories:
  - jobs-tools (10): list, get, create, update, complete, cancel, line items, schedule, reschedule
  - customers-tools (7): list, get, create, update, delete, search, addresses
  - estimates-tools (8): list, get, create, update, send, approve, decline, convert to job
  - invoices-tools (6): list, get, create, send, mark paid, list payments
  - employees-tools (6): list, get, create, update, schedule, time entries
  - dispatch-tools (3): dispatch board, assign employee, availability
  - tags-tools (5): list, create, delete, add to job/customer
  - notifications-tools (3): list, send, mark read
  - reviews-tools (3): list, get, request review
  - reporting-tools (3): revenue, job completion, employee performance
- 16 React MCP Apps for rich UI:
  - job-dashboard, job-detail, job-grid
  - customer-detail, customer-grid
  - estimate-builder, estimate-grid
  - invoice-dashboard, invoice-detail
  - dispatch-board
  - employee-schedule, employee-performance
  - review-dashboard, revenue-dashboard
  - tag-manager, notification-center
- Complete types, comprehensive README, full package.json

2026-02-12 17:39:57 -05:00

8.9 KiB

Raw Blame History

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

8.9 KiB Raw Blame History