# 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"
)
```