ServiceTitan MCP Server

AI-native interface to ServiceTitan for home services contractors

An MCP (Model Context Protocol) server that gives AI assistants direct access to ServiceTitan — the leading field service management platform. Built for HVAC, plumbing, electrical, and other home services contractors who want their AI to manage jobs, look up customers, schedule appointments, dispatch technicians, and track invoices.

🛠️ Available Tools

Tool	Description
search_customers	Search customers by name, phone, email, or address
get_customer	Get full customer details including contacts and service history
list_jobs	List jobs with filters for status, date range, customer, or technician
get_job	Get complete job details including notes and assigned tech
create_job	Create a new job for a customer
get_available_appointments	Find available appointment slots in a date range
schedule_appointment	Schedule or reschedule a job appointment
list_technicians	List active technicians with current status and schedule
dispatch_technician	Assign a technician to a job appointment
get_invoice	Get invoice details with line items and payment status
list_unpaid_invoices	List unpaid/overdue invoices for collections follow-up

🚀 Quick Start

1. Get ServiceTitan API Credentials

1. Go to the ServiceTitan Developer Portal
2. Create an application in My Apps to get your App Key
3. Have your ServiceTitan admin generate Client ID and Client Secret for your environment
4. Note your Tenant ID from ServiceTitan settings

2. Configure Environment

cp .env.example .env
# Edit .env with your credentials:
#   ST_CLIENT_ID=your_client_id
#   ST_CLIENT_SECRET=your_client_secret
#   ST_APP_KEY=your_app_key
#   ST_TENANT_ID=your_tenant_id
#   ST_ENVIRONMENT=production  # or "integration" for sandbox

3. Install & Run

# Install
pip install -e .

# Run the MCP server
servicetitan-mcp

# Or run directly
python -m servicetitan_mcp.server

4. Connect to Your AI

Add to your MCP client configuration (e.g., Claude Desktop):

{
  "mcpServers": {
    "servicetitan": {
      "command": "servicetitan-mcp",
      "env": {
        "ST_CLIENT_ID": "your_client_id",
        "ST_CLIENT_SECRET": "your_client_secret",
        "ST_APP_KEY": "your_app_key",
        "ST_TENANT_ID": "your_tenant_id",
        "ST_ENVIRONMENT": "production"
      }
    }
  }
}

🔐 Authentication

ServiceTitan uses OAuth2 Client Credentials grant:

• Auth endpoint: https://auth.servicetitan.io/connect/token (production) or https://auth-integration.servicetitan.io/connect/token (sandbox)
• API base: https://api.servicetitan.io (production) or https://api-integration.servicetitan.io (sandbox)
• Required headers: Authorization: Bearer {token} + ST-App-Key: {app_key}
• Tokens are cached and auto-refreshed before expiry

Required Environment Variables

Variable	Description
ST_CLIENT_ID	OAuth2 Client ID
ST_CLIENT_SECRET	OAuth2 Client Secret
ST_APP_KEY	ServiceTitan Application Key
ST_TENANT_ID	Your ServiceTitan Tenant ID
ST_ENVIRONMENT	production or integration (default: production)

📦 ServiceTitan API Modules Used

Module	Base Path	Entities
CRM	/crm/v2/tenant/{id}/	Customers, Contacts, Locations, Bookings
Job Planning	/jpm/v2/tenant/{id}/	Jobs, Appointments, Job Types
Dispatch	/dispatch/v2/tenant/{id}/	Technician Shifts, Appointment Assignments
Accounting	/accounting/v2/tenant/{id}/	Invoices, Payments
Settings	/settings/v2/tenant/{id}/	Technicians, Employees, Business Units

🧪 Development

# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Lint
ruff check src/ tests/

☁️ Deployment

Apify Marketplace

Coming Day 3 — pay-per-event billing on Apify

The apify_actor/ directory contains the deployment scaffold for the Apify platform.

mcp.so

Coming — listing at mcp.so

Smithery

Coming — listing at smithery.ai

📋 Roadmap

• [x] Day 1: Core scaffold — 11 tools covering the contractor workflow loop
• [ ] Day 2: Validate against ServiceTitan sandbox, fix endpoint paths, add integration tests
• [ ] Day 3: Apify Actor deployment, pay-per-event billing, marketplace listings

📄 License

MIT