Housecall Pro MCP Server

An Apify Actor that provides AI agents with access to the Housecall Pro API v1 through the Model Context Protocol (MCP). Connect your own HCP API key and let AI agents manage customers, jobs, estimates, leads, invoices, scheduling, and more.

Features

• 80 tools across 18 categories of the Housecall Pro API
• Bring your own API key — each user provides their own HCP credentials, stored securely
• Automatic timezone conversion — all datetime fields are converted between UTC and your local timezone
• Per-page pagination billing — GET requests with auto-pagination charge per page fetched, not per tool call
• Confirmation-guarded deletions — destructive operations require a two-step confirmation to prevent accidents
• Transparent rate limiting — HCP API rate limit info is surfaced directly to the AI agent
• Modular architecture — organized by API category for easy maintenance and expansion

Setup

Input Configuration

Parameter	Required	Description
hcpApiKey	Yes	Your Housecall Pro API key (stored as a secret). Generate one at HCP Settings > API Keys.
timezone	Yes	Your company's IANA timezone (e.g. America/New_York). Must match your HCP Company Profile timezone.

Connecting an MCP Client

The Actor runs in standby mode. Only the user who started the run can use the MCP; the token must be the same Apify API token as the account that started the run (Apify MCP model).

Mode A: Claude → Apify MCP server (mcp.apify.com) → this Actor (recommended)

Connect Claude to the hosted Apify MCP server and add this Actor as a tool. Use the mcp.apify.com configurator or add to claude_desktop_config.json:

{
  "mcpServers": {
    "apify": {
      "url": "https://mcp.apify.com?tools=flow_logic_automation/flow-logic-automation-hcp-mcp",
      "headers": {
        "Authorization": "Bearer YOUR_APIFY_TOKEN"
      }
    }
  }
}

Replace YOUR_APIFY_TOKEN with your Apify API token. Replace flow_logic_automation/flow-logic-automation-hcp-mcp with your Actor's full name (username/actor-name from Apify Console) if different. You will provide HCP API key and timezone when the tool is used or via the configurator.

Mode B: Claude → direct run URL

After you start the Actor on Apify, open Live View and copy the run URL (e.g. https://xxxxx.runs.apify.net). In Claude Desktop → Settings → Developer → Edit Config:

{
  "mcpServers": {
    "hcp-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://YOUR_RUN_URL_HERE/mcp",
        "--header",
        "Authorization: Bearer YOUR_APIFY_API_TOKEN"
      ]
    }
  }
}

Or use the query token form (add ?token=YOUR_APIFY_TOKEN to the /mcp URL if your client supports it). Replace YOUR_RUN_URL_HERE with the run URL (no trailing slash) and use the same Apify API token as the account that started the run. Restart Claude Desktop after saving.

Use the container URL from Live View; the run must stay Running and Ready.

Troubleshooting

• 401 Unauthorized: Use the exact Apify API token for the account that started the run. Copy it again from Integrations; no extra spaces.
• Server disconnected: Verify the run is Ready (log shows "Housecall Pro MCP Server listening on port …"). Test with: curl -v --max-time 15 -X POST "https://YOUR_RUN_URL/mcp" -H "Content-Type: application/json" -H "Authorization: Bearer YOUR_TOKEN" -d '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}},"id":1}' — you should get HTTP 200 and JSON, not 401.
• Claude logs: macOS ~/Library/Logs/Claude/. Restart Claude fully (quit and reopen) after config changes.

Alternative: Apify hosted MCP — If you use Apify’s main MCP server (mcp.apify.com), add this Actor in the tools parameter so it appears as a tool there; use the same Apify token for auth.

Pricing

Every tool call is billed at $0.01 per event (GET, POST, PUT, or DELETE). Auto-paginate fetches charge once per page.

Tool Catalog

Customers (7 tools)

Tool	Method	Description
hcp_get_customers	GET	Search/list customers by name, phone, email, or address
hcp_create_customer	POST	Create a new customer record
hcp_get_customer	GET	Get a specific customer by ID
hcp_update_customer	PUT	Update fields on an existing customer
hcp_get_customer_addresses	GET	List all addresses for a customer
hcp_create_customer_address	POST	Add a new address to a customer
hcp_get_customer_address	GET	Get a specific address by ID

Jobs (21 tools)

Tool	Method	Description
hcp_get_jobs	GET	Search/list jobs with date, status, and employee filters
hcp_create_job	POST	Create a new job for a customer
hcp_get_job	GET	Get a specific job by ID
hcp_add_job_attachment	POST	Upload a file attachment to a job
hcp_get_job_line_items	GET	List line items for a job
hcp_add_job_line_item	POST	Add a single line item
hcp_bulk_update_job_line_items	PUT	Bulk create/update line items
hcp_update_job_line_item	PUT	Update a single line item
hcp_delete_job_line_item	DELETE	Delete a line item (requires confirmation)
hcp_update_job_schedule	PUT	Update a job's schedule
hcp_delete_job_schedule	DELETE	Remove schedule from a job (requires confirmation)
hcp_dispatch_job	PUT	Dispatch a job to employees
hcp_get_job_materials	GET	List input materials for a job
hcp_bulk_update_job_materials	PUT	Bulk create/update job materials
hcp_add_job_tag	POST	Add a tag to a job
hcp_remove_job_tag	DELETE	Remove a tag from a job (requires confirmation)
hcp_add_job_note	POST	Add a note to a job
hcp_delete_job_note	DELETE	Delete a job note (requires confirmation)
hcp_create_job_link	POST	Add a link to a job
hcp_lock_job	POST	Lock a single job
hcp_lock_jobs_by_date_range	POST	Lock jobs in a date range

Job Appointments (4 tools)

Tool	Method	Description
hcp_get_job_appointments	GET	List all appointments for a job
hcp_create_job_appointment	POST	Add an appointment to a multi-day job
hcp_update_job_appointment	PUT	Update an appointment
hcp_delete_job_appointment	DELETE	Delete an appointment (requires confirmation)

Job Invoices (1 tool)

Tool	Method	Description
hcp_get_job_invoices	GET	Get invoice details for a job

Estimates (12 tools)

Tool	Method	Description
hcp_get_estimates	GET	List estimates with filters
hcp_create_estimate	POST	Create an estimate with options and line items
hcp_get_estimate	GET	Get a specific estimate by ID
hcp_add_estimate_option_attachment	POST	Upload file to an estimate option
hcp_get_estimate_option_line_items	GET	List line items for an option
hcp_bulk_update_estimate_option_line_items	PUT	Bulk update option line items
hcp_create_estimate_option_link	POST	Add a link to an option
hcp_update_estimate_option_schedule	PUT	Update option schedule
hcp_create_estimate_option_note	POST	Add a note to an option
hcp_delete_estimate_option_note	DELETE	Delete a note (requires confirmation)
hcp_decline_estimate_options	POST	Decline estimate options
hcp_approve_estimate_options	POST	Approve estimate options

Leads (4 tools)

Tool	Method	Description
hcp_create_lead	POST	Create a lead (with existing or inline customer)
hcp_get_leads	GET	List leads with filters (customer, employee, status, tags)
hcp_get_lead	GET	Get a single lead by ID
hcp_convert_lead	POST	Convert a lead to an estimate or job

Lead Sources (3 tools)

Tool	Method	Description
hcp_get_lead_sources	GET	List lead sources (with name search)
hcp_create_lead_source	POST	Create a new lead source
hcp_update_lead_source	PUT	Update a lead source name (editable only)

Lead Line Items (1 tool)

Tool	Method	Description
hcp_get_lead_line_items	GET	List all line items for a lead

Invoices (3 tools)

Tool	Method	Description
hcp_get_invoices	GET	List invoices with filters (status, customer, dates, payment method)
hcp_get_invoice	GET	Get a single invoice by UUID
hcp_preview_invoice	GET	Preview an invoice as rendered HTML

Employees (1 tool)

Tool	Method	Description
hcp_get_employees	GET	List active employees (IDs, names, roles)

Tags (3 tools)

Tool	Method	Description
hcp_get_tags	GET	List all tags
hcp_create_tag	POST	Create a new tag
hcp_update_tag	PUT	Rename an existing tag

Job Types (3 tools)

Tool	Method	Description
hcp_get_job_types	GET	List job types (with optional name filter)
hcp_create_job_type	POST	Create a new job type
hcp_update_job_type	PUT	Rename an existing job type

Price Book Services (1 tool)

Tool	Method	Description
hcp_get_price_book_services	GET	Search/list price book services with filters

Material Categories (4 tools)

Tool	Method	Description
hcp_get_material_categories	GET	List categories (root or subcategories)
hcp_create_material_category	POST	Create a new material category
hcp_update_material_category	PUT	Update a category name
hcp_delete_material_category	DELETE	Delete a category (requires confirmation)

Materials (4 tools)

Tool	Method	Description
hcp_get_materials	GET	List price book materials under a category
hcp_create_material	POST	Create a new material
hcp_update_material	PUT	Update a material
hcp_delete_material	DELETE	Delete a material (requires confirmation)

Schedule (3 tools)

Tool	Method	Description
hcp_get_schedule_windows	GET	Get company business hours configuration
hcp_update_schedule_windows	PUT	Update business hours and bookable windows
hcp_get_booking_windows	GET	Get actual available booking slots for a time range

Events (2 tools)

Tool	Method	Description
hcp_get_events	GET	List events with filters and sorting
hcp_get_event	GET	Get a single event by ID

Webhooks (2 tools)

Tool	Method	Description
hcp_create_webhook_subscription	POST	Subscribe company to webhook events
hcp_delete_webhook_subscription	DELETE	Unsubscribe from webhooks (requires confirmation)

Checklists (1 tool)

Tool	Method	Description
hcp_get_checklists	GET	Get checklists for specific jobs or estimates

Key Behaviors

Timezone Handling

All datetime fields are automatically handled:

• Outgoing (to HCP API): Local times provided by the AI agent are converted to UTC before sending
• Incoming (from HCP API): UTC datetimes in responses are converted to your configured local timezone

Configure your timezone to match your HCP Company Profile settings.

Auto-Pagination

List endpoints support an auto_paginate parameter. When enabled, the tool fetches all available pages (up to 50 for safety) and returns the complete dataset. Each page fetched incurs a separate GET charge ($0.01).

Destructive Operation Safety

All DELETE operations use a two-step confirmation pattern:

1. First call (without confirm: true) returns a warning message describing what will be deleted
2. Second call (with confirm: true) executes the deletion

Only the confirmed deletion is charged.

Monetary Values

All monetary values in the HCP API are in cents. For example, unit_price: 5000 means $50.00.

Resources

• Housecall Pro API Documentation
• Apify Actor Documentation
• Model Context Protocol