README.md
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) orhttps://auth-integration.servicetitan.io/connect/token(sandbox) - API base:
https://api.servicetitan.io(production) orhttps://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
Tools 11
search_customersSearch customers by name, phone, email, or addressget_customerGet full customer details including contacts and service historylist_jobsList jobs with filters for status, date range, customer, or technicianget_jobGet complete job details including notes and assigned techcreate_jobCreate a new job for a customerget_available_appointmentsFind available appointment slots in a date rangeschedule_appointmentSchedule or reschedule a job appointmentlist_techniciansList active technicians with current status and scheduledispatch_technicianAssign a technician to a job appointmentget_invoiceGet invoice details with line items and payment statuslist_unpaid_invoicesList unpaid/overdue invoices for collections follow-upEnvironment Variables
ST_CLIENT_IDrequiredOAuth2 Client IDST_CLIENT_SECRETrequiredOAuth2 Client SecretST_APP_KEYrequiredServiceTitan Application KeyST_TENANT_IDrequiredYour ServiceTitan Tenant IDST_ENVIRONMENTproduction or integration (default: production)Try it
→Find the customer details for John Doe and list his recent service history.
→List all unpaid invoices that are currently overdue.
→What are the available appointment slots for next Tuesday?
→Dispatch the next available technician to the job with ID 12345.
→Create a new job for customer ID 98765 for a plumbing repair.