ServiceTitan MCP Server

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

Built by Rowvyn — See the case study →

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
• Dashboard-matched revenue — verified on production data using the same Reporting API source that powers ST's own dashboard

Features

• 467 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-matched revenue — intel_revenue_summary pulls from the same source as ST's own dashboard
• 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
• Streamable HTTP remote deployment — deploy to Fly.io (or anywhere) and connect via mcp-remote
• Built-in health check — st_health_check validates auth and tenant access (no config details exposed)

Quick Start

Prerequisites

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

npx (recommended)

No install needed — runs directly:

{
  "mcpServers": {
    "servicetitan": {
      "command": "npx",
      "args": ["-y", "@rowvyn/servicetitan-mcp"],
      "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": "production"
      }
    }
  }
}

⚠️ ST_ENVIRONMENT defaults to integration. If you're connecting to a live ServiceTitan account, you must set ST_ENVIRONMENT to production or you'll get silent auth failures and empty results.

Install globally

npm install -g @rowvyn/servicetitan-mcp
servicetitan-mcp       # stdio transport (for Claude Desktop)
servicetitan-mcp-sse     # SSE transport (legacy remote)
servicetitan-mcp-http    # Streamable HTTP transport (recommended remote)

From source

npm install
npm run build

Claude Desktop

For a local checkout, point Claude Desktop at the built stdio entrypoint:

Add to your claude_desktop_config.json:

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

Remote Deployment (Streamable HTTP)

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

# On the server
ST_CLIENT_ID=... ST_CLIENT_SECRET=... ST_APP_KEY=... ST_TENANT_ID=... \
  ST_MCP_API_KEY=your-secret node build/streamable-http.js

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

SSE remains available at build/sse.js for backward compatibility, but it is deprecated. Prefer Streamable HTTP at /mcp for new deployments.

Tool Catalog

467 tools registered across 15 domains:

With ST_READONLY=true (default), all tools are registered but write and delete operations are blocked at execution time with a clear error message (Readonly mode: operation not permitted). Use ST_CONFIRM_WRITES=true to require _confirmed: true on write operations, or confirm: true on delete operations.

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

Business unit name matching uses exact → prefix → contains fallback. Technician name matching uses case-insensitive substring search. 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, and tool responses will keep timestamps in UTC instead of your local display timezone.

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/domains/loader.ts scans src/domains/*/index.ts 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) — all tools are registered but write and delete operations are blocked at execution time
• Confirmation workflow — delete tools require confirm: true (returns preview payload when missing); write tools optionally require _confirmed: true via ST_CONFIRM_WRITES=true (returns error when missing)
• Audit logging — all write/delete executions emit [AUDIT] log records with timestamp, tool, operation, resource, and sanitized params (secrets/tokens redacted)

Troubleshooting

npm permission errors (EACCES)

If you see EACCES: permission denied errors when Claude Desktop tries to start the server, your npm cache directory is likely owned by root (common when Node was installed with sudo).

Fix:

sudo chown -R $(whoami) ~/.npm

Then restart Claude Desktop.

Server won't start / "Could not connect to MCP server"

1. Test outside Claude Desktop first:

   npx -y @rowvyn/servicetitan-mcp
   

   If this fails, the issue is with Node, npm, or your environment — not Claude Desktop.

2. Check Node version: node -v — requires Node 22 or newer.

3. Check for conflicting MCP installs: If you previously installed a different ServiceTitan MCP server, remove it:

   npm ls -g --depth=0 | grep -i servicetitan
   npm uninstall -g <old-package-name>
   npx clear-npx-cache
   

4. Verify your claude_desktop_config.json has no leftover entries from a previous MCP server. Only one servicetitan entry should exist under mcpServers.

Auth failures / $0 revenue / empty results

• Set ST_ENVIRONMENT to production. This is the #1 cause. The default is integration, which authenticates against ServiceTitan's sandbox — not your live account. You'll get valid auth tokens that return zero data.
• Verify credentials match: ST_CLIENT_ID and ST_CLIENT_SECRET must be from the same ServiceTitan app. You can't mix credentials from different apps.
• Check ST_TENANT_ID: Must match the tenant associated with your app in the ServiceTitan developer portal.

Claude Desktop logs

Claude Desktop writes MCP server logs to:

• macOS: ~/Library/Logs/Claude/mcp*.log
• Windows: %APPDATA%\Claude\logs\mcp*.log

Contributing

See CONTRIBUTING.md.

Security

See SECURITY.md for the vulnerability disclosure policy.

License

MIT