ServiceTitan MCP Server (Enterprise)

Enterprise-grade MCP server for the ServiceTitan API, built for safe production use with domain-level control, write safeguards, and high-value intelligence tools.

Features

• Domain filtering via ST_DOMAINS to expose only the tool groups you want.
• Read-only mode enabled by default (ST_READONLY=true) for safer production rollout.
• Safety layer in the registry:
  • Optional confirmation for write tools (ST_CONFIRM_WRITES=true).
  • Required confirmation for all delete tools.
  • Audit logging for write/delete operations with sensitive fields sanitized.
• 6 intelligence tools that combine multiple ServiceTitan endpoints into operational and revenue insights.
• Dynamic domain loading from src/domains/* with centralized tool registration and stats.
• Built-in st_health_check system tool for connectivity and config verification.

Quick Start

Prerequisites

• Node.js 22 or newer
• ServiceTitan API credentials:
  • OAuth Client ID
  • OAuth Client Secret
  • ST App Key
  • Tenant ID

Installation

npm install
npm run build

Configuration

1. Copy .env.example to .env.
2. Set all required variables.
3. Keep ST_READONLY=true until you are ready to allow write/delete tools.

Notes:

• Boolean env vars accept: true, false, 1, 0 (case-insensitive).
• Empty ST_DOMAINS means all domains are enabled.
• 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/jobs near day boundaries. For example, an EST tenant should use ST_TIMEZONE=America/New_York so that "Feb 1" means midnight Eastern, not midnight UTC.

MCP Client Setup

Build first:

npm run build

Use the built entrypoint: build/index.js.

Claude Desktop

Add to Claude Desktop MCP config:

{
  "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_ENVIRONMENT": "integration",
        "ST_READONLY": "true",
        "ST_CONFIRM_WRITES": "false",
        "ST_MAX_RESPONSE_CHARS": "100000",
        "ST_DOMAINS": "",
        "ST_LOG_LEVEL": "info",
        "ST_TIMEZONE": ""
      }
    }
  }
}

Cursor

Add to Cursor settings.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_ENVIRONMENT": "integration",
        "ST_READONLY": "true",
        "ST_CONFIRM_WRITES": "false",
        "ST_MAX_RESPONSE_CHARS": "100000",
        "ST_DOMAINS": "",
        "ST_LOG_LEVEL": "info",
        "ST_TIMEZONE": ""
      }
    }
  }
}

Windsurf

Add to Windsurf MCP config:

{
  "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_ENVIRONMENT": "integration",
        "ST_READONLY": "true",
        "ST_CONFIRM_WRITES": "false",
        "ST_MAX_RESPONSE_CHARS": "100000",
        "ST_DOMAINS": "",
        "ST_LOG_LEVEL": "info",
        "ST_TIMEZONE": ""
      }
    }
  }
}

OpenClaw / Generic StdIO Host

Any MCP host that supports stdio can run:

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_ENVIRONMENT=integration \
ST_READONLY=true \
ST_CONFIRM_WRITES=false \
ST_MAX_RESPONSE_CHARS=100000 \
ST_LOG_LEVEL=info \
ST_TIMEZONE="" \
node /absolute/path/to/servicetitan-mcp-server/build/index.js

Available Domains

Tool counts are from:

grep -rc 'registry.register(' src/domains/

Intelligence Tools

The intelligence domain includes 6 high-value analytical tools:

Revenue: API vs Dashboard Accuracy

intel_revenue_summary uses ServiceTitan's Reporting API (Report 175: "Revenue") to calculate totals. This matches the ST dashboard exactly because 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. The invoices API returns invoice-level totals (which include tax and exclude non-job revenue), while the jobs API only captures job-level totals. Both miss the non-job revenue component that ST's internal reporting engine includes.

If you need invoice-level detail (line items, individual invoice totals), use accounting_invoices_list. For dashboard-matching revenue figures, use intel_revenue_summary.

Safety Features

• Read-only mode (ST_READONLY=true by default):
  • Non-read tools are skipped during registration.
  • Helps validate production connectivity before enabling mutations.
• Confirmation workflow:
  • All delete tools require confirm=true.
  • Write tools require confirm=true when ST_CONFIRM_WRITES=true.
  • When confirmation is missing, the tool returns a preview/warning payload instead of executing.
• Audit logging:
  • All write/delete executions emit [AUDIT] log records.
  • Captures timestamp, tool, domain, operation, resource, ID, params, success/failure.
  • Sensitive fields (secret, password, token, key) are removed from logged params.

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/

To run compiled server directly:

npm run start

Architecture Overview

• Domain module pattern:
  • Each domain lives in src/domains/<domain>/.
  • Domain index.ts exports a loader that registers all tools in that domain.
• Dynamic domain discovery:
  • src/index.ts scans src/domains/* and imports each domain index.js at runtime.
• Central registry:
  • ToolRegistry handles filtering (ST_DOMAINS, ST_READONLY), confirmation wrapping, audit hooks, and registration stats.
• API client layer:
  • ServiceTitanClient manages OAuth client-credentials auth, token refresh, retry-on-401/429 behavior, and {tenant} path replacement.
• System tool:
  • st_health_check validates auth, tenant access, active config, and registration summary.

License

MIT