313 lines
10 KiB
Markdown
313 lines
10 KiB
Markdown
> **🚀 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
|
|
|
|
[](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).
|