servicetitan-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@servicetitan-mcp Find customer by phone 555-1234 and show their recent jobs"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
servicetitan-mcp
A read-only MCP server over the ServiceTitan API: six task-shaped tools (find a customer, look at their jobs, their money, resolve an external id) instead of a thin wrapper over ServiceTitan's own endpoints. ReadOnlyClient defines only get and get_page — no write path exists.
See docs/DESIGN.md for the reasoning behind these choices.
The credentials rule
The MCP client config carries exactly one setting: ST_ENV_FILE, a path — never a secret directly. Everything else (client id, secret, app key, tenant id) lives in the file it points at, chmod 600, outside the repo and outside any MCP config: MCP configs get pasted into chats, and some (.mcp.json) are designed to be committed.
permission_warning checks the file's mode at startup and warns — doesn't refuse to start — if it's looser than 600. Full reasoning in docs/DESIGN.md.
{
"mcpServers": {
"servicetitan": {
"command": "/absolute/path/to/servicetitan-mcp/.venv/bin/servicetitan-mcp",
"env": { "ST_ENV_FILE": "/home/you/.config/servicetitan-mcp/env" }
}
}
}command must be an absolute path into this project's .venv — an MCP client launches from an arbitrary directory, so a bare python may resolve to an interpreter without mcp/httpx/st_mcp installed.
Related MCP server: jobber-mcp
The six tools
Tool | Answers | Reach for it when |
| Who is this, by name/phone/external id? | You have a human identifier, not a ServiceTitan id. One match returns the full card; several return a short list to disambiguate. |
| Full card for one customer: contacts, locations, 5 recent jobs, external ids. | You already have the numeric customer id — from |
| Which jobs match these filters, and when's the next visit? | You want a list of jobs by customer, date range, or status. Not for finding a customer — that's |
| Everything about one job: appointments, technicians. | You have a job id and need its full appointment history. |
| Balance, estimates, invoices, payments — for one customer, one call. | Any "what do they owe" or billing-history question. |
| Which ServiceTitan customer has this id in another system? | You're crossing over from a CRM synced into ServiceTitan via |
Job types, business units, and payment types are also exposed as MCP resources (cached client-side) rather than tools, and back the id→name substitution above.
Token savings, measured against a live tenant
chars / 4, on the same four ServiceTitan reads:
tokens | |
| 1516 |
| 1001 |
| 69 |
| 43 |
| 28 |
| 318 |
22x against pretty-printed JSON, 15x against minified, per call — and customer_overview is one model round trip for four ServiceTitan reads, where an endpoint-shaped tool surface would spend four.
ServiceTitan findings
totalCountisnullunless the request sendsincludeTotal=true.jpm/appointmentshas no batch filter —jobIds,jobId=<csv>, repeatedjobIdare all ignored or wrong; onlyjobId=<single>works.sales/estimatesignorescustomerId; reachable only viajobIdorlocationId.A 404 on an appointment's assigned-technicians means "nobody assigned yet", not "not found" — the API's own "could not" that actually means "none".
Setup
Requires Python 3.11+.
python -m venv .venv
.venv/bin/pip install -e ".[dev]"Create the env file ST_ENV_FILE will point at (e.g. ~/.config/servicetitan-mcp/env), chmod 600 it, and fill in:
ST_CLIENT_ID=...
ST_CLIENT_SECRET=...
ST_APP_KEY=...
ST_TENANT_ID=...
# Optional:
ST_AUTH_HOST=auth.servicetitan.io
ST_API_HOST=api.servicetitan.io
ST_APP_GUID=... # required only for find_by_external_id
ST_EXTERNAL_ID_KEY=... # the externalData key find_customer treats as an idST_AUTH_HOST/ST_API_HOST default to production; ServiceTitan's sandbox uses different hosts (*-integration.*) and both must match the credentials' environment, or the token request 400s with invalid_client.
Registering it with a client
Both routes need an absolute path to the servicetitan-mcp console script in this project's .venv, and ST_ENV_FILE. Neither carries a secret.
Claude Code:
claude mcp add servicetitan -s user \
-e ST_ENV_FILE=/home/you/.config/servicetitan-mcp/env \
-- /home/you/servicetitan-mcp/.venv/bin/servicetitan-mcp-s user registers it for every project on the machine — prefer it over -s project, which writes a committable .mcp.json. Verify with claude mcp list (✔ Connected).
Claude Desktop: copy claude_desktop_config_example.json, fix the two paths, and merge it into the client's own config.
Run the tests with .venv/bin/pytest. Nothing in the suite makes a live ServiceTitan call — every test uses the fake clients in tests/conftest.py.
Available Tools
6 toolscustomer_moneyA
Balance, estimates, invoices, and payments for one customer, in one response.
Use for any "what do they owe" or billing-history question. Needs a customer id; find_customer supplies one.
Inputs: customer_id (required), limit. Returns: result
customer_overviewA
Full card for one customer: contacts, locations, 5 recent jobs, external ids.
Needs a ServiceTitan customer id; use find_customer if you only have a name or phone.
Inputs: customer_id (required). Returns: result
find_by_external_idA
Find a customer by an externalData key/value pair — another system's id.
Requires ST_APP_GUID. Use when you hold an id from a CRM synced into ServiceTitan.
Inputs: key (required), value (required). Returns: result
find_customerA
Find a customer by name, phone, or external id — no ServiceTitan id needed.
One match returns the full card (contacts, locations, recent jobs); several return a short list to choose from. Email lookup is not supported by ServiceTitan.
Inputs: query (required), limit. Returns: result
find_jobsA
List jobs with the next appointment inlined. Dates are ISO (2026-08-01).
An invalid status returns the valid list, not an empty result. Not for finding a customer — use find_customer.
Inputs: limit, since, until, status, +1 more. Returns: result
job_detailA
One job with its appointments and assigned technicians.
For several jobs at once — a customer's list, a date range, a status — use find_jobs instead of calling this once per job.
Inputs: job_id (required). Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
find_customer, customer_overview, and find_by_external_id all locate customers, with find_customer already supporting external IDs, causing potential confusion. However, descriptions clarify that customer_overview requires a ServiceTitan ID and find_by_external_id needs a specific externalData key, so agents can usually pick correctly.
Tool names mix patterns: find_customer and find_jobs use verb_noun, customer_overview and job_detail use noun_noun, and find_by_external_id uses verb_preposition_noun. All are snake_case and readable, but the inconsistent structure makes it harder to predict tool names.
Six tools is a reasonable count for a customer/job lookup server, not overwhelming. However, the overlap between find_customer and find_by_external_id means the count is slightly padded, preventing a perfect score.
The server covers customer retrieval, job lookups, and billing summaries well for read-only scenarios. Missing write operations like creating/updating customers or jobs, and there is no direct way to fetch all appointments independently, which are notable gaps for a full lifecycle.
Maintenance
Related MCP Connectors
Unofficial remote MCP server for Less Annoying CRM: OAuth 2.1, read-only grants, 10 tools.
Read-only MCP server for ClassQuill, a tutoring-business-management platform.
One OAuth connector for your team's remote MCP servers, with Tool Packs, guardrails and logs.
Read-only MCP server that answers questions about turva.dev from its published data. Five tools return JSON: the service catalog with prices, contact and operator details, engagement principles and dated agent-readiness and security evidence with verification links. Connect over Streamable HTTP. You need no API key. The server does not scan other websites or run audits.
Related MCP Servers
- AlicenseBqualityBmaintenanceConnects AI assistants to ServiceTitan with a default catalog of 264 read-only tools for CRM, dispatch, accounting, reporting, and analytics. Supports focused discovery profiles; write operations are experimental and require explicit opt-in.26461 npm5MIT
- AlicenseAqualityDmaintenanceCustomer-hosted, read-only MCP server for Jobber operations workflows. It helps owners query Jobber for action lists, overdue invoices, stale requests, estimate/job follow-up, and safe read-only GraphQL validation.661 npm1MIT
- AlicenseNot gradedqualityDmaintenanceA remote MCP server that exposes the ServiceTitan API as tools, enabling Claude and other clients to manage customers, jobs, pricebook, invoicing, and more with write safety and built-in observability.MIT
- AlicenseAqualityDmaintenanceMCP server for HeyMax CRM API, providing read-only tools to query pipelines, services, and other CRM data.1012 npmMIT