mcpengine/servers/servicetitan

ServiceTitan MCP Server

Complete Model Context Protocol (MCP) server for ServiceTitan field service management platform.

Features

🔧 55 MCP Tools across 10 categories:

Jobs Management (9 tools)

• servicetitan_list_jobs - List jobs with filters
• servicetitan_get_job - Get job details
• servicetitan_create_job - Create new job
• servicetitan_update_job - Update job
• servicetitan_cancel_job - Cancel job
• servicetitan_list_job_appointments - List job appointments
• servicetitan_create_job_appointment - Create appointment
• servicetitan_reschedule_appointment - Reschedule appointment
• servicetitan_get_job_history - Get job history

Customer Management (9 tools)

• servicetitan_list_customers - List customers
• servicetitan_get_customer - Get customer details
• servicetitan_create_customer - Create customer
• servicetitan_update_customer - Update customer
• servicetitan_search_customers - Search customers
• servicetitan_list_customer_contacts - List contacts
• servicetitan_create_customer_contact - Create contact
• servicetitan_list_customer_locations - List locations
• servicetitan_create_customer_location - Create location

Invoice Management (8 tools)

• servicetitan_list_invoices - List invoices
• servicetitan_get_invoice - Get invoice details
• servicetitan_create_invoice - Create invoice
• servicetitan_update_invoice - Update invoice
• servicetitan_list_invoice_items - List invoice items
• servicetitan_add_invoice_item - Add invoice item
• servicetitan_list_invoice_payments - List payments
• servicetitan_add_invoice_payment - Add payment

Estimates (6 tools)

• servicetitan_list_estimates - List estimates
• servicetitan_get_estimate - Get estimate
• servicetitan_create_estimate - Create estimate
• servicetitan_update_estimate - Update estimate
• servicetitan_convert_estimate_to_job - Convert to job
• servicetitan_list_estimate_items - List items

Technician Management (6 tools)

• servicetitan_list_technicians - List technicians
• servicetitan_get_technician - Get technician details
• servicetitan_create_technician - Create technician
• servicetitan_update_technician - Update technician
• servicetitan_get_technician_performance - Get performance
• servicetitan_list_technician_shifts - List shifts

Dispatch (4 tools)

• servicetitan_list_dispatch_zones - List zones
• servicetitan_get_dispatch_board - Get dispatch board
• servicetitan_assign_technician - Assign technician
• servicetitan_get_dispatch_capacity - Get capacity

Equipment (5 tools)

• servicetitan_list_equipment - List equipment
• servicetitan_get_equipment - Get equipment
• servicetitan_create_equipment - Create equipment
• servicetitan_update_equipment - Update equipment
• servicetitan_list_location_equipment - List by location

Memberships (6 tools)

• servicetitan_list_memberships - List memberships
• servicetitan_get_membership - Get membership
• servicetitan_create_membership - Create membership
• servicetitan_update_membership - Update membership
• servicetitan_cancel_membership - Cancel membership
• servicetitan_list_membership_types - List types

Reporting (4 tools)

• servicetitan_revenue_report - Revenue analytics
• servicetitan_technician_performance_report - Performance metrics
• servicetitan_job_costing_report - Job costing
• servicetitan_call_tracking_report - Call tracking

Marketing (4 tools)

• servicetitan_list_campaigns - List campaigns
• servicetitan_get_campaign - Get campaign
• servicetitan_list_leads - List leads
• servicetitan_get_lead_source_analytics - Lead source ROI

📊 20 MCP Apps (React-based UI)

• Job Dashboard - Overview of all jobs
• Job Detail - Detailed job information
• Job Grid - Searchable job grid
• Customer Detail - Complete customer profile
• Customer Grid - Customer database
• Invoice Dashboard - Revenue overview
• Invoice Detail - Invoice line items
• Estimate Builder - Create estimates
• Dispatch Board - Visual scheduling
• Technician Dashboard - Performance overview
• Technician Detail - Individual tech stats
• Equipment Tracker - Equipment by location
• Membership Manager - Recurring memberships
• Revenue Dashboard - Revenue trends
• Performance Metrics - KPIs
• Call Tracking - Inbound call analytics
• Lead Source Analytics - Marketing ROI
• Schedule Calendar - Calendar view
• Appointment Manager - Appointment management
• Marketing Dashboard - Campaign performance

Installation

npm install

Configuration

Create a .env file in the server root:

# Required
SERVICETITAN_CLIENT_ID=your_client_id
SERVICETITAN_CLIENT_SECRET=your_client_secret
SERVICETITAN_TENANT_ID=your_tenant_id
SERVICETITAN_APP_KEY=your_app_key

# Optional
SERVICETITAN_BASE_URL=https://api.servicetitan.io
PORT=3000
MODE=stdio  # or "http"

Getting ServiceTitan API Credentials

1. Register Developer Account

   • Visit https://developer.servicetitan.io
   • Sign up for developer access

2. Create Application

   • Create a new application in the developer portal
   • Note your client_id, client_secret, and app_key

3. Get Tenant ID

   • Your tenant ID is provided by ServiceTitan
   • Usually visible in your ServiceTitan admin dashboard

Usage

Stdio Mode (MCP Protocol)

For use with Claude Desktop or other MCP clients:

npm run build
npm start

Add to your MCP client configuration (e.g., claude_desktop_config.json):

{
  "mcpServers": {
    "servicetitan": {
      "command": "node",
      "args": ["/path/to/servicetitan/dist/main.js"],
      "env": {
        "SERVICETITAN_CLIENT_ID": "your_client_id",
        "SERVICETITAN_CLIENT_SECRET": "your_client_secret",
        "SERVICETITAN_TENANT_ID": "your_tenant_id",
        "SERVICETITAN_APP_KEY": "your_app_key"
      }
    }
  }
}

HTTP Mode (Web Apps)

For browser-based UI apps:

MODE=http PORT=3000 npm start

Visit http://localhost:3000/apps to access the React apps.

API Architecture

Authentication

• OAuth2 client_credentials flow
• Automatic token refresh
• 5-minute token expiry buffer

Pagination

• Automatic pagination handling
• Configurable page size (default: 50, max: 500)
• getPaginated() for automatic multi-page fetching

Error Handling

• Comprehensive error messages
• Rate limit detection
• Network error recovery
• 401/403 authentication errors
• 429 rate limit errors
• 500+ server errors

API Endpoints

Base URL: https://api.servicetitan.io

• Jobs: /jpm/v2/tenant/{tenant}/
• Customers: /crm/v2/tenant/{tenant}/
• Invoices: /accounting/v2/tenant/{tenant}/
• Estimates: /sales/v2/tenant/{tenant}/
• Technicians: /settings/v2/tenant/{tenant}/
• Dispatch: /dispatch/v2/tenant/{tenant}/
• Equipment: /equipment/v2/tenant/{tenant}/
• Memberships: /memberships/v2/tenant/{tenant}/
• Reporting: /reporting/v2/tenant/{tenant}/
• Marketing: /marketing/v2/tenant/{tenant}/

Development

# Build
npm run build

# Watch mode
npm run dev

# Start server
npm start

Project Structure

servicetitan/
├── src/
│   ├── clients/
│   │   └── servicetitan.ts         # API client with OAuth2
│   ├── tools/
│   │   ├── jobs-tools.ts           # Job management tools
│   │   ├── customers-tools.ts      # Customer tools
│   │   ├── invoices-tools.ts       # Invoice tools
│   │   ├── estimates-tools.ts      # Estimate tools
│   │   ├── technicians-tools.ts    # Technician tools
│   │   ├── dispatch-tools.ts       # Dispatch tools
│   │   ├── equipment-tools.ts      # Equipment tools
│   │   ├── memberships-tools.ts    # Membership tools
│   │   ├── reporting-tools.ts      # Reporting tools
│   │   └── marketing-tools.ts      # Marketing tools
│   ├── types/
│   │   └── index.ts                # TypeScript types
│   ├── ui/
│   │   └── react-app/              # 20 React MCP apps
│   ├── server.ts                   # MCP server
│   └── main.ts                     # Entry point
├── package.json
├── tsconfig.json
└── README.md

License

MIT

Support

• ServiceTitan API Documentation: https://developer.servicetitan.io/docs
• ServiceTitan Developer Portal: https://developer.servicetitan.io
• MCP Protocol: https://modelcontextprotocol.io