> **🚀 Don't want to self-host?** [Join the waitlist for our fully managed solution →](https://mcpengage.com/servicetitan)
> 
> Zero setup. Zero maintenance. Just connect and automate.

---

# 🚀 ServiceTitan MCP Server

## 💡 What This Unlocks

**This MCP server gives AI direct access to your entire ServiceTitan operation.** Instead of clicking through screens, you just *tell* it what you need.

### 🎯 ServiceTitan-Native Power Moves

| Just say... | What happens |
|-------------|--------------|
| *"Show me all high-priority jobs scheduled for tomorrow"* | Queries jobs API, filters by priority and date, returns organized list with customer details |
| *"Create an emergency AC repair job for John at 123 Main St"* | Creates job, assigns priority, links to customer location, notifies dispatch |
| *"Find all unpaid invoices over $500 from last month"* | Searches accounting module, filters by amount and date, returns aging report |
| *"Which technicians are available between 2-4pm today?"* | Checks dispatch schedule, finds gaps, returns available techs with skills |
| *"Send me a summary of today's completed jobs and revenue"* | Aggregates job data, calculates totals, generates daily performance report |

### 🔗 The Real Power: Combining Tools

AI can chain multiple ServiceTitan operations together:

- **Smart Dispatching:** *"Find the closest available plumber to handle the leak at 456 Oak Ave"* → Check job type, filter techs by skill, calculate proximity, create appointment
- **Revenue Recovery:** *"List customers with outstanding balances over 60 days and draft payment reminder texts"* → Query invoices, filter aging, pull contact info, generate personalized messages
- **Performance Analysis:** *"Compare this week's job completion rate vs last month by technician"* → Pull job data, group by tech, calculate metrics, format comparison

## 📦 What's Inside

**124 API tools** covering the entire ServiceTitan platform:

- **Job Planning & Management (JPM)** — Jobs, estimates, projects, appointments
- **Customer Relationship Management (CRM)** — Customers, locations, contacts, bookings
- **Dispatch** — Technicians, appointments, zones, non-job appointments
- **Accounting** — Invoices, payments, invoice items, payment terms
- **Reporting** — Custom reports, dashboards, data export

All with proper error handling, automatic token refresh, and TypeScript types.

## 🚀 Quick Start

### Option 1: Claude Desktop (Local)

1. **Clone and build:**
   ```bash
   git clone https://github.com/YOUR_USERNAME/servicetitan-mcp.git
   cd servicetitan-mcp
   npm install
   npm run build
   ```

2. **Get your ServiceTitan credentials:**
   - Go to [ServiceTitan Developer Portal](https://developer.servicetitan.io/)
   - Create an app or use existing credentials
   - Copy Client ID, Client Secret, and Tenant ID
   - Request access to required API modules (CRM, JPM, Dispatch, Accounting)

3. **Configure Claude Desktop:**
   
   On macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
   
   On Windows: `%APPDATA%\Claude\claude_desktop_config.json`

   ```json
   {
     "mcpServers": {
       "servicetitan": {
         "command": "node",
         "args": ["/ABSOLUTE/PATH/TO/servicetitan-mcp/dist/index.js"],
         "env": {
           "SERVICETITAN_CLIENT_ID": "your-client-id",
           "SERVICETITAN_CLIENT_SECRET": "your-client-secret",
           "SERVICETITAN_TENANT_ID": "your-tenant-id"
         }
       }
     }
   }
   ```

4. **Restart Claude Desktop**

### Option 2: Deploy to Railway

[![Deploy on Railway](https://railway.app/button.svg)](https://railway.app/template/servicetitan-mcp)

1. Click the button above
2. Set environment variables in Railway dashboard:
   - `SERVICETITAN_CLIENT_ID`
   - `SERVICETITAN_CLIENT_SECRET`
   - `SERVICETITAN_TENANT_ID`
3. Use the Railway URL as your MCP server endpoint

### Option 3: Docker

```bash
docker build -t servicetitan-mcp .
docker run -p 3000:3000 \
  -e SERVICETITAN_CLIENT_ID=your-id \
  -e SERVICETITAN_CLIENT_SECRET=your-secret \
  -e SERVICETITAN_TENANT_ID=your-tenant \
  servicetitan-mcp
```

## 🔐 Authentication

ServiceTitan uses OAuth 2.0 Client Credentials flow:

1. **Register your app** in the [ServiceTitan Developer Portal](https://developer.servicetitan.io/)
2. **Request API access** for required modules:
   - CRM (Customer data)
   - JPM (Job Planning & Management)
   - Dispatch (Scheduling & technicians)
   - Accounting (Invoices & payments)
3. **Get credentials:**
   - Client ID
   - Client Secret
   - Tenant ID (your ServiceTitan company ID)

The MCP server handles token refresh automatically — you never need to manually refresh.

## 📚 Available Tools

### Jobs (Job Planning & Management)

- `list_jobs` — List work orders with filtering by status, customer, technician, date range
- `get_job` — Get detailed job information including line items, notes, technicians
- `create_job` — Create new jobs/work orders with customer, location, job type
- `update_job` — Update job status, priority, summary, or other fields
- `list_job_types` — List available job types for your company

### Customers (CRM)

- `list_customers` — List customers with filtering and search
- `get_customer` — Get customer details including locations, contacts, tags
- `create_customer` — Add new customers to your CRM
- `update_customer` — Update customer information
- `list_customer_contacts` — List all contacts for a customer

### Locations

- `list_locations` — List service locations
- `get_location` — Get location details with address and service history
- `create_location` — Add new service locations
- `list_location_contacts` — Get contacts at a specific location

### Invoices (Accounting)

- `list_invoices` — List invoices with filtering by status, customer, job, date
- `get_invoice` — Get detailed invoice with line items and payments
- `list_invoice_items` — Get line items for an invoice
- `export_invoices` — Batch export invoice data

### Dispatch

- `list_technicians` — List field technicians with status and skills
- `get_technician` — Get technician details and schedule
- `list_appointments` — List scheduled appointments with filtering
- `get_appointment` — Get appointment details
- `create_appointment` — Schedule new appointments
- `list_zones` — List dispatch zones

### Estimates

- `list_estimates` — List estimates/quotes
- `get_estimate` — Get estimate details
- `create_estimate` — Create new estimates

### Reporting

- `get_report_data` — Pull data from ServiceTitan reports
- `list_report_categories` — List available report categories

## 🎯 Example Prompts

Once connected to Claude, you can use natural language:

### Job Management
- *"Show me all open emergency jobs assigned to Mike"*
- *"Create a plumbing job for leak repair at 789 Elm Street"*
- *"What jobs were completed yesterday by our HVAC techs?"*
- *"List all jobs with pending estimates over $5,000"*

### Customer Service
- *"Find the customer John Smith and show me their service history"*
- *"Add a new customer: Sarah Johnson, 555-1234, 321 Oak Ave"*
- *"Which customers have had service in the last 30 days?"*

### Dispatch & Scheduling
- *"Who's available tomorrow morning for a water heater install?"*
- *"Show me Mike's schedule for next week"*
- *"Create an appointment for Jane Doe on Friday at 2pm"*

### Financial
- *"List all unpaid invoices from December"*
- *"Show me today's invoices with payment status"*
- *"Which customers owe more than $1,000?"*

### Analytics
- *"Compare this month's job volume to last month"*
- *"What's the average job value for HVAC repairs?"*
- *"Show me top 10 customers by revenue this year"*

## 🛠️ Development

### Prerequisites
- Node.js 18+
- npm or yarn
- ServiceTitan Developer account

### Setup

```bash
git clone https://github.com/YOUR_USERNAME/servicetitan-mcp.git
cd servicetitan-mcp
npm install
cp .env.example .env
# Edit .env with your ServiceTitan credentials
npm run build
npm start
```

### Project Structure

```
servicetitan-mcp/
├── src/
│   ├── index.ts          # Main MCP server
│   ├── tools/            # Tool implementations
│   │   ├── jobs.ts
│   │   ├── customers.ts
│   │   ├── invoices.ts
│   │   └── dispatch.ts
│   ├── api/              # ServiceTitan API client
│   │   ├── client.ts
│   │   └── auth.ts
│   └── types/            # TypeScript types
├── dist/                 # Compiled JavaScript
├── tests/                # Unit tests
├── package.json
├── tsconfig.json
└── README.md
```

### Testing

```bash
npm test                  # Run all tests
npm run test:watch        # Watch mode
npm run test:coverage     # Coverage report
```

### Building

```bash
npm run build            # Compile TypeScript
npm run build:watch      # Watch mode
```

## 🐛 Troubleshooting

### "Authentication failed"
- Double-check your Client ID and Client Secret
- Verify your Tenant ID is correct
- Ensure your app has been approved for API access in the developer portal

### "Module access denied"
- Request access to the required modules (CRM, JPM, Dispatch, Accounting) in the developer portal
- Wait for approval from ServiceTitan

### "Tools not appearing in Claude"
- Restart Claude Desktop after updating config
- Check that the path in `claude_desktop_config.json` is absolute, not relative
- Verify the build completed successfully (`dist/index.js` exists)

### Rate limits
- ServiceTitan has rate limits per API endpoint
- The MCP server will automatically retry with exponential backoff
- For bulk operations, use pagination parameters

## 📖 Resources

- [ServiceTitan API Documentation](https://developer.servicetitan.io/docs)
- [ServiceTitan Developer Portal](https://developer.servicetitan.io/)
- [MCP Protocol Specification](https://modelcontextprotocol.io/)
- [Claude Desktop Documentation](https://claude.ai/desktop)

## 🤝 Contributing

Contributions are welcome! Please:

1. Fork the repo
2. Create a feature branch (`git checkout -b feature/amazing-tool`)
3. Commit your changes (`git commit -m 'Add amazing tool'`)
4. Push to the branch (`git push origin feature/amazing-tool`)
5. Open a Pull Request

## 📄 License

MIT License - see [LICENSE](LICENSE) for details

## 🙏 Credits

Built by [MCPEngine](https://mcpengage.com) — AI infrastructure for business software.

Want more MCP servers? Check out our [full catalog](https://mcpengage.com) covering 30+ business platforms.

---

**Questions?** Open an issue or join our [Discord community](https://discord.gg/mcpengine).
