ServiceTitan MCP Server

The only MCP server for the ServiceTitan API — 505 tools across 15 domains, plus 10 intelligence tools that turn raw API data into business decisions.

Why

• ServiceTitan has no official MCP server or developer tooling beyond REST docs

• Raw API access is friction-heavy — OAuth token management, module-prefix routing, pagination, and response parsing all fall on you

• This server handles all of that and adds 10 intelligence tools that aggregate multiple endpoints into operational insights

• Revenue accuracy within 0.001% of ServiceTitan's own dashboard (verified on production data using Report 175 — the same source ST's internal engine uses)

Features

• 505 tools across 15 domains — CRM, dispatch, accounting, payroll, inventory, marketing, and more

• 10 intelligence tools — composite analytics that aggregate multiple API calls into revenue summaries, ops snapshots, technician scorecards, and more

• Dashboard-accurate revenue — intel_revenue_summary uses Report 175 to match ST's dashboard within 0.001%

• Read-only by default — ST_READONLY=true out of the box; write tools only activate when you're ready

• Safety layer — confirmation workflow for writes/deletes, audit logging with sensitive field redaction

• Domain filtering — expose only the tool groups you need via ST_DOMAINS

• Name-based filtering — pass businessUnitName or technicianName instead of numeric IDs; resolved via 30-minute cache

• LLM-optimized responses — response shaping trims API noise and structures data for AI consumption

• SSE remote deployment — deploy to Fly.io (or anywhere) and connect via mcp-remote

• Built-in health check — st_health_check validates auth, tenant access, and registration summary

Quick Start

Prerequisites

• Node.js 22 or newer

• ServiceTitan API credentials: Client ID, Client Secret, App Key, Tenant ID

Install & Build

npm install
npm run build

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "servicetitan": {
      "command": "node",
      "args": ["/absolute/path/to/servicetitan-mcp-server/build/index.js"],
      "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_TIMEZONE": "America/New_York"
      }
    }
  }
}

Works the same way in Cursor, Windsurf, and any other MCP-compatible host.

Generic stdio

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_TIMEZONE=America/New_York \
node /absolute/path/to/servicetitan-mcp-server/build/index.js

Remote Deployment (SSE)

Deploy to Fly.io or any server, then connect via mcp-remote:

# On the server
ST_MCP_API_KEY=your-secret node build/sse.js

{
  "mcpServers": {
    "servicetitan": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://your-instance.fly.dev/sse",
        "--header",
        "x-api-key: YOUR_MCP_API_KEY"
      ]
    }
  }
}

Tool Catalog

505 tools registered across 15 domains:

The full 505 count includes all read, write, and delete tools. With ST_READONLY=true (default), write and delete tools are skipped at registration time.

Intelligence Tools

The real differentiator. These 10 tools aggregate multiple API calls and report endpoints into operational insights — the kind of answers that would otherwise require custom BI tooling.

These tools are why this server exists. Raw CRUD tools are table stakes. Intelligence tools turn API data into business decisions.

Revenue Accuracy

intel_revenue_summary uses ServiceTitan's Reporting API (Report 175: "Revenue") to calculate totals. This is the same source ST's own dashboard uses — which means it includes:

• Completed Revenue — revenue from completed jobs

• Non-Job Revenue — membership fees, add-ons, and other income not tied to a specific job

• Adjustment Revenue — credits, adjustments, and corrections

Raw invoice or job endpoint sums will not match the dashboard. Both miss non-job revenue. For dashboard-matching figures, use intel_revenue_summary. For invoice-level detail, use accounting_invoices_list.

Name-Based Filtering

Most intelligence tools accept businessUnitName and technicianName as alternatives to numeric IDs:

# Instead of:
intel_revenue_summary(startDate="2026-01-01", endDate="2026-04-01", businessUnitId=12345)

# Use:
intel_revenue_summary(startDate="2026-01-01", endDate="2026-04-01", businessUnitName="HVAC")

Name matching uses exact → prefix → contains fallback. If no match is found, the tool returns all data with a warning.

Configuration

Copy .env.example to .env and fill in your credentials.

Required

Optional

Set ST_TIMEZONE to your tenant's local timezone. Without it, date-only queries (e.g. startDate: "2026-02-01") are interpreted as UTC midnight — which can miss or include invoices and jobs near day boundaries for non-UTC tenants.

Boolean env vars accept: true, false, 1, 0 (case-insensitive).

Architecture

The server is built as a layered system: Config → OAuth Client → Domain Registry → MCP Server.

• Domain module pattern — each domain lives in src/domains/<domain>/ and exports a loader that registers its tools

• Dynamic discovery — src/index.ts scans src/domains/* and imports each domain at runtime

• Central registry — ToolRegistry handles domain filtering, read-only enforcement, confirmation wrapping, and audit logging

• OAuth client — ServiceTitanClient manages client-credentials auth, token refresh, retry-on-401/429, and {tenant} path injection

• Response shaping — transformer layer strips API noise and structures responses for LLM consumption

• Intelligence layer — composite tools fan out to multiple endpoints and report IDs, then aggregate results

See ARCHITECTURE.md for the full deep-dive: route table, response shaping pipeline, intelligence layer design, and safety system.

CLI Companion

If you prefer working from the terminal directly, servicetitan-cli is a companion st binary built from the same auth and intelligence layer:

# Install
npm install -g @rowvyn/servicetitan-cli

# Same intelligence — no MCP required
st revenue --period ytd --compact
st snapshot --compact

# Pipe into your agent
st customers list --all --json | your-agent process

The CLI and this MCP server share the same design philosophy: push the business question into the tool name, minimize schema overhead, and shape responses for AI consumption.

Comparison

Development

npm run dev        # tsc --watch
npm run test       # vitest run
npm run lint       # eslint src/
npm run typecheck  # tsc --noEmit
npm run build      # compile to build/
npm run start      # run compiled server

Safety

• Read-only mode (ST_READONLY=true by default) — write and delete tools are skipped at registration

• Confirmation workflow — delete tools always require confirm=true; write tools optionally require it via ST_CONFIRM_WRITES=true; missing confirmation returns a preview payload instead of executing

• Audit logging — all write/delete executions emit [AUDIT] log records with timestamp, tool, operation, resource, and sanitized params (secrets/tokens redacted)

Contributing

See CONTRIBUTING.md.

Security

See SECURITY.md for the vulnerability disclosure policy.

License

MIT