ServiceFusion MCP Server

ServiceFusion MCP Server

A Model Context Protocol (MCP) server that provides AI agents with standardized access to ServiceFusion API operations.

Features

• OAuth 2.0 Authentication: Automatic token management and refresh
• Complete CRUD Operations: Create, read, update, and delete customers and jobs
• Type-Safe Interface: Full TypeScript support with validation
• Resource Access: MCP resources for browsing customers and jobs
• Error Handling: Comprehensive error handling and validation

Available Tools

Connection Management

• sf_test_connection - Test ServiceFusion API connectivity
• sf_get_api_status - Get current authentication status

Customer Operations

• sf_create_customer - Create new customers with contacts and locations
• sf_get_customers - Search and retrieve customers with pagination

Job Operations

• sf_create_job - Create new work orders/jobs
• sf_get_jobs - Search and retrieve jobs with filtering
• sf_update_job - Update job status and details
• sf_delete_job - Delete/cancel jobs

Available Resources

• servicefusion://customers - Paginated list of customers
• servicefusion://jobs - Paginated list of jobs
• servicefusion://customer/{id} - Individual customer details
• servicefusion://job/{id} - Individual job details
• servicefusion://api-status - API connection status

Installation

1. Clone and install dependencies:

npm install

2. Set up environment variables:

cp .env.example .env
# Edit .env with your ServiceFusion credentials

3. Build the project:

npm run build

Usage

Running the MCP Server

npm start

Development Mode

npm run dev

Testing

npm test

Configuration

Set the following environment variables:

• SERVICEFUSION_CLIENT_ID - Your ServiceFusion API client ID
• SERVICEFUSION_CLIENT_SECRET - Your ServiceFusion API client secret
• SERVICEFUSION_BASE_URL - (Optional) API base URL (defaults to https://api.servicefusion.com)

Integration with Claude Desktop

Add to your Claude Desktop MCP configuration:

{
  "mcpServers": {
    "servicefusion": {
      "command": "node",
      "args": ["/path/to/servicefusion-mcp/build/index.js"],
      "env": {
        "SERVICEFUSION_CLIENT_ID": "your_client_id",
        "SERVICEFUSION_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

API Examples

Create a Customer

await sf_create_customer({
  customer_name: "ABC Property Management",
  contacts: [{
    fname: "John",
    lname: "Doe", 
    contact_type: "Primary",
    phone: "555-1234",
    email: "[email protected]"
  }],
  locations: [{
    street_1: "123 Main St",
    city: "Dallas",
    state_prov: "TX",
    postal_code: "75201"
  }]
});

Create a Job

await sf_create_job({
  check_number: "WO-12345",
  customer_id: 123456,
  description: "HVAC repair needed",
  category: "Maintenance",
  priority: "High",
  street_1: "123 Main St",
  city: "Dallas",
  state_prov: "TX"
});

Search Jobs

await sf_get_jobs({
  page: 1,
  customer_name: "ABC Property",
  status: "Scheduled",
  updated_since: "2025-01-01T00:00:00Z"
});

Data Models

Customer

• customer_name (required)
• parent_customer (optional) - For hierarchical customers
• contacts[] - Array of contact information
• locations[] - Array of location information

Job

• check_number (required) - Unique identifier
• customer_id (required) - Associated customer
• description (required) - Job description
• status - Job status (Scheduled, In Progress, Completed, etc.)
• priority - Job priority (Normal, High, Low)
• custom_fields[] - Custom field values

Error Handling

The server includes comprehensive error handling for:

• Authentication failures (automatic token refresh)
• API rate limits and timeouts
• Invalid input validation
• Network connectivity issues

Contributing

1. Make changes to TypeScript files in src/
2. Build with npm run build
3. Test with npm test
4. Submit pull requests with tests

License

MIT