@servihero/n8n-nodes-housecall-pro

HouseCall Pro MCP Server

This MCP server provides integration with the HouseCall Pro API, allowing chat agents to manage customer information, and simulate scheduling functionality.

Features

The server exposes the following tools:

1. get_estimates - Get a list of estimates from HouseCall Pro
2. get_jobs - Get a list of jobs from HouseCall Pro
3. get_booking_windows - Get available booking windows
4. get_schedule_windows - Get the company's schedule windows (business hours)
5. search_customers - Search for existing customers by phone or email
6. create_customer - Create a new customer record
7. get_available_slots - Retrieve available appointment slots
8. check_specific_availability - Check specific time slot availability
9. create_appointment - Create a new appointment

Installation

The MCP server is installed and configured for Claude. The configuration is stored in:

• ~/Library/Application Support/Claude/claude_desktop_config.json
• ~/Library/Application Support/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

Usage

To use these tools from Claude, you need to provide an agent_id when invoking the tools. The agent_id is used to retrieve the corresponding HouseCall Pro API key from the database. For example:

// Example usage in Claude
use_mcp_tool(
  "housecall-pro-server",
  "get_available_slots",
  {
    "agent_id": "your_agent_id",
    "start_date": "2025-03-27",
    "end_date": "2025-04-02"
  }
)

Security Improvements

The server now uses agent_id instead of directly passing API keys:

1. API keys are stored securely in the database
2. The server retrieves the API key based on the agent_id
3. This prevents API keys from being exposed in chat logs
4. Allows for better tracking and management of API usage

Appointment Creation Workflow

When creating an appointment with the create_appointment tool, the server follows this workflow:

1. Check availability - Verifies if the requested time slot is available
2. Customer management - Two-step process:
   • Find existing customer - Searches for customer by phone or email
   • Create new customer if needed - If no existing customer is found, creates a new one with:
     • Properly formatted address (street, city, state, zip)
     • Lead source set to "Chat"
3. Create booking - Creates the appointment with the customer ID

This approach ensures that returning customers are properly linked to their existing records, while new customers are created with all required information.

Current API Status

After extensive testing with the HouseCall Pro API, we've discovered:

1. ✅ Customer API Works: We can successfully list and create customers
2. ❌ Availability/Booking APIs Unavailable: The availability and booking endpoints mentioned in the documentation return 404 errors

Our implementation adapts to these limitations by:

• Using the customer API for actual customer management
• Simulating availability and booking functionality based on customer data

Test Scripts

Several test scripts are included to verify the server's functionality:

• test-housecall-pro-server.js: Tests the MCP server protocol
• api-test.js: Tests API connectivity with multiple base URLs
• test-create-customer.js: Tests customer creation via the HouseCall Pro API
• test-agent-id.js: Tests the new agent_id functionality

Example:

node test-agent-id.js <agent_id>

Implementation Notes

• Customer creation works with the actual HouseCall Pro API
• Availability checks are simulated based on customer data
• Booking functionality uses a hybrid approach of customer API and simulated scheduling
• API keys are securely managed through the Supabase database

Deployment to Railway

To deploy this MCP server to Railway, follow these steps:

1. Sign up for Railway: If you haven't already, create an account at Railway.app.

2. Install Railway CLI (optional, for local development):

   npm i -g @railway/cli
   railway login

3. Deploy using Railway Dashboard:

   • Fork or clone this repository to your GitHub account
   • In Railway dashboard, click "New Project" → "Deploy from GitHub repo"
   • Select your repository
   • Railway will automatically detect the Node.js project and build settings

4. Configure Environment Variables:

   • In the Railway dashboard, go to your project
   • Navigate to the "Variables" tab
   • Add the environment variables listed in .env.example:
     • SUPABASE_URL
     • SUPABASE_SERVICE_ROLE_KEY
     • HOUSECALL_PRO_API_KEY (if not using Supabase for key storage)

5. Deploy and Monitor:

   • Railway will automatically build and deploy your application
   • You can monitor logs in the "Deployments" tab
   • The URL of your deployed application will be available in the "Settings" tab

6. Update MCP Configuration:

   • Update your Claude MCP configuration to point to your new Railway-hosted server URL

Maintaining the Deployment

• Railway will automatically rebuild and redeploy when you push changes to your GitHub repository
• To update environment variables, use the Railway dashboard or CLI
• Monitor usage in the Railway dashboard to stay within free tier limits or upgrade as needed