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

Go to the ServiceTitan Developer Portal
Create an application in My Apps to get your App Key
Have your ServiceTitan admin generate Client ID and Client Secret for your environment
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

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

ServiceTitan MCP Server

ServiceTitan MCP Server

🛠️ Available Tools

🚀 Quick Start

1. Get ServiceTitan API Credentials

2. Configure Environment

3. Install & Run

4. Connect to Your AI

🔐 Authentication

Required Environment Variables

📦 ServiceTitan API Modules Used

🧪 Development

☁️ Deployment

Apify Marketplace

mcp.so

Smithery

📋 Roadmap

📄 License

Reviews