110 lines
2.6 KiB
Markdown
110 lines
2.6 KiB
Markdown
# ServiceTitan MCP Server
|
|
|
|
MCP server for [ServiceTitan](https://www.servicetitan.com/) API integration. Access jobs, customers, invoices, technicians, and appointments for field service management.
|
|
|
|
## Setup
|
|
|
|
```bash
|
|
npm install
|
|
npm run build
|
|
```
|
|
|
|
## Environment Variables
|
|
|
|
| Variable | Required | Description |
|
|
|----------|----------|-------------|
|
|
| `SERVICETITAN_CLIENT_ID` | Yes | App client ID from ServiceTitan developer portal |
|
|
| `SERVICETITAN_CLIENT_SECRET` | Yes | App client secret |
|
|
| `SERVICETITAN_TENANT_ID` | Yes | Tenant/company ID |
|
|
|
|
## API Endpoints
|
|
|
|
- **API Base:** `https://api.servicetitan.io`
|
|
- **Auth:** `https://auth.servicetitan.io/connect/token`
|
|
|
|
## Tools
|
|
|
|
### Jobs
|
|
- **list_jobs** - List work orders with filtering by status, customer, technician
|
|
- **get_job** - Get detailed job information
|
|
- **create_job** - Create new jobs/work orders
|
|
|
|
### Customers (CRM)
|
|
- **list_customers** - List customers with filtering
|
|
- **get_customer** - Get customer details with locations and contacts
|
|
|
|
### Accounting
|
|
- **list_invoices** - List invoices with filtering by status, customer, job
|
|
|
|
### Dispatch
|
|
- **list_technicians** - List field technicians
|
|
- **list_appointments** - List scheduled appointments
|
|
|
|
## Usage with Claude Desktop
|
|
|
|
Add to your `claude_desktop_config.json`:
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"servicetitan": {
|
|
"command": "node",
|
|
"args": ["/path/to/mcp-servers/servicetitan/dist/index.js"],
|
|
"env": {
|
|
"SERVICETITAN_CLIENT_ID": "your-client-id",
|
|
"SERVICETITAN_CLIENT_SECRET": "your-client-secret",
|
|
"SERVICETITAN_TENANT_ID": "your-tenant-id"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
## Authentication
|
|
|
|
ServiceTitan uses OAuth 2.0 Client Credentials flow:
|
|
1. Register your app in the ServiceTitan Developer Portal
|
|
2. Request access to required API modules (CRM, JPM, Dispatch, Accounting)
|
|
3. Get client credentials and tenant ID
|
|
|
|
The MCP server automatically handles token refresh.
|
|
|
|
## API Modules
|
|
|
|
ServiceTitan API is organized into modules:
|
|
- **jpm** - Job Planning & Management (jobs, estimates)
|
|
- **crm** - Customer Relationship Management (customers, locations)
|
|
- **dispatch** - Dispatch (technicians, appointments, zones)
|
|
- **accounting** - Accounting (invoices, payments)
|
|
|
|
## Examples
|
|
|
|
List scheduled jobs:
|
|
```
|
|
list_jobs(status: "Scheduled", pageSize: 25)
|
|
```
|
|
|
|
Get customer with details:
|
|
```
|
|
get_customer(customer_id: 12345)
|
|
```
|
|
|
|
Create a new job:
|
|
```
|
|
create_job(
|
|
customerId: 12345,
|
|
locationId: 67890,
|
|
jobTypeId: 111,
|
|
priority: "High",
|
|
summary: "AC repair - no cooling"
|
|
)
|
|
```
|
|
|
|
List tomorrow's appointments:
|
|
```
|
|
list_appointments(
|
|
startsOnOrAfter: "2024-01-15T00:00:00Z",
|
|
startsOnOrBefore: "2024-01-15T23:59:59Z"
|
|
)
|
|
```
|