Servicetitan MCP Server (Jrhoades1)

ServiceTitan MCP服务器

A. 模型上下文协议 （MCP）服务器，将Claude Desktop连接到您在American Leak Detection的ServiceTitan帐户。

在不暴露任何客户个人信息的情况下，向克劳德提出有关技术人员工作和业务绩效的自然语言问题。

你可以问什么

"How many jobs did Freddy do last week?"
"How much revenue did Tom bring in last week?"
"What was total business revenue last week?"
"Compare all technicians for last week — who brought in the most?"
"How many no-charge jobs were there last week?"
"What does Freddy's schedule look like this week?"
"Who had the most scheduled hours last week? Who started earliest?"
"What is the average revenue per job by job type trending over the last 90 days?"
"Show revenue trend by business unit for the last 3 months."
"List all active technicians."
"What job types does Freddy do? Break down his job mix for the last 90 days."
"Compare all technicians by job type for the last 90 days."
"How many cancellations were there last month? How many were late?"
"Show discount activity for last month."
"Show all recall jobs for the last 90 days."
"How many GO BACKs were true recalls vs Set Test jobs last month?"
"What is our recall rate by technician? Who is causing the most rework?"
"Show me all jobs tagged Set Test for the last 90 days."
"Search job summaries for 'FG going' for last month."

运作原理

克劳德桌面→ MCP服务器→ ServiceTitan API（只读）

所有数据在返回给Claude之前都会被聚合。客户姓名、地址和联系信息如下 从不 发送给克劳德——只有工作计数、状态、收入总额和技术人员姓名。

______________________________________________________________________

先决条件

• Python 3.11或更新版本
• 具有API证书的ServiceTitan开发人员帐户
• Windows上安装了Claude Desktop

______________________________________________________________________

设置

1.克隆并创建virtualenv

git clone  servicetitan-mcp-server
cd servicetitan-mcp-server
python -m venv venv
venv\Scripts\activate
pip install -r requirements.txt

2.配置凭据

复制示例env文件并填写您的ServiceTitan凭据：

copy .env.example .env

编辑 .env:

ST_CLIENT_ID=your_client_id_here
ST_CLIENT_SECRET=your_client_secret_here
ST_APP_KEY=your_app_key_here
ST_TENANT_ID=your_numeric_tenant_id
ST_AUTH_URL=https://auth.servicetitan.io/connect/token
ST_API_BASE=https://api.servicetitan.io

在哪里可以找到这些： ServiceTitan开发者门户→ 您的应用程序→ 资格证书。 ST_TENANT_ID 是ServiceTitan URL中可见的数字ID。

3.测试连接

python servicetitan_mcp_server.py --check

预期产量：

Connection OK — ServiceTitan authentication successful.
You can now add this server to Claude Desktop.

如果失败，请仔细检查您的 .env 资格证书。

______________________________________________________________________

Claude桌面配置

Windows注意事项： Claude Desktop是一个Windows应用商店（UWP）应用程序。配置文件为 不 在标准中 %APPDATA%\Claude\ 文件夹——它位于MSIX包位置。

配置文件位置（Windows）

%LOCALAPPDATA%\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\claude_desktop_config.json

在文本编辑器中打开该文件。添加 mcpServers block（更新路径以匹配您的安装）：

{
  "mcpServers": {
    "servicetitan": {
      "command": "C:\\Users\\Tracy\\Projects\\servicetitan-mcp-server\\venv\\Scripts\\python.exe",
      "args": [
        "C:\\Users\\Tracy\\Projects\\servicetitan-mcp-server\\servicetitan_mcp_server.py"
      ]
    }
  }
}

使用完整的绝对路径——Claude Desktop可以从任何工作目录启动此服务器。

应用配置

编辑配置文件后，完全退出并重新启动Claude Desktop。

在新聊天中，您应该看到工具指示器(⚡ 或锤子图标）确认服务器已加载。

______________________________________________________________________

可用工具（共20个）

作业工具

list_technicians

列出所有在职技术人员。可选择按名称过滤。

例子： “列出所有技术人员”或“查找名为Danny的技术人员”

get_technician_jobs

显示特定技术人员在日期范围内的作业计数，按状态细分。

参数： technician_name, start_date, end_date

get_jobs_summary

显示某一日期范围内所有技术人员的作业总计。

参数： start_date, end_date

get_jobs_by_type

按工作类型名称筛选的单个工作级别记录，显示所有分配的技术人员（主要+添加）。可根据技术人员或状态进行筛选。

参数： job_types （逗号分隔的名称）， start_date, end_date, technician_name （可选）， status （“全部”、“已完成”或“已取消”）

收入工具

get_technician_revenue

特定技术人员的收入明细——总收入、收费与免费以及每份工作的收入。

参数： technician_name, start_date, end_date

get_revenue_summary

日期范围内的全业务收入总额。

参数： start_date, end_date

get_no_charge_jobs

日期范围内免费作业的计数和百分比。

参数： start_date, end_date

compare_technicians

排行榜比较所有技术人员：工作、收入、每份工作的收入和免费计数。按收入递减排序。

参数： start_date, end_date

get_revenue_trend

按类别（工作类型或业务部门）划分的每个工作的平均收入，按月细分。显示哪些类别呈上升或下降趋势。最好是60-90天。

参数： group_by （“job_type”或“business_unit”）， start_date, end_date

计划工具

get_technician_schedule

特定技术人员的每日预约时间表，显示开始/结束时间和状态。

参数： technician_name, start_date, end_date

compare_technician_hours

按预约时间和最早开始时间比较所有技术人员。按小时降序排列。

参数： start_date, end_date

注： 日程安排工具显示 *预定的* 预约时间-不是实际的登录/退出时间（时钟数据无法通过ServiceTitan API获得）。

分析工具

get_technician_job_mix

按工作类型细分技术人员的工作——计数、收入、每种类型的平均美元/份工作。显示他们的工作和收入中来自每种工作类型的百分比。

参数： technician_name, start_date, end_date

compare_technician_job_mix

公司范围内的矩阵，比较所有工作类型的所有技术人员。显示谁处理什么工作，以及他们的美元/工作与公司平均水平的比较。可选地筛选到单个作业类型。

参数： job_type （可选）， start_date, end_date

get_cancellations

通过时间分析取消的作业记录——每个作业被取消的时间有多早，以及是否是延迟取消（在预约后24小时内）。标签显示为取消原因代理。

参数： technician_name （可选）， late_only （可选）， start_date, end_date

get_technician_discounts

发票中每个技术人员的折扣和信用活动。通过负行项目检测折扣。显示折扣计数、总金额和常见SKU。

参数： technician_name （可选）， min_discount_amount （可选）， start_date, end_date

召回工具

get_recalls

工作地点 recallForId 不是空的——这些是通过“召回…”作业操作预订的真正的ServiceTitan召回。显示每次召回及其原始作业（如果超出日期范围，则显示注释）、原始和召回之间的天数，以及带有PII警告的作业摘要。

参数： technician_name （可选——通过召回技术过滤）， business_unit （可选）， start_date, end_date

get_callback_chains

组按其原始作业调用作业，以显示完整的回调链。显示每条链需要多少辆卡车滚动以及机会成本（召回次数×每份工作的平均收入）。有助于识别哪些工作会产生重复访问。

参数： technician_name （可选——按原始作业技术筛选）， min_chain_length （默认2——要显示的最小总访问量）， start_date, end_date

get_recall_summary

按技术人员、业务部门或工作类型细分的召回率——归因于原始工作的技术/BU（谁造成了返工）。显示召回率%、平均召回天数和机会成本。包括一个GO BACK分类块，将真正的召回与Set Test作业和未分类的GO BACK分开。

参数： group_by （“技术员”、“业务单位”或“job_type”）， start_date, end_date

get_jobs_by_tag

按标记名称筛选的作业。标签名在客户端解析为ID（不区分大小写）。如果找不到标记名称，则列出所有可用的标记。可用于查找“Set Test”、“CC on FILE”或任何其他标记的作业。

参数： tag_names （逗号分隔的名称，必填）， technician_name （可选）， start_date, end_date

search_job_summaries

在工作总结笔记中进行不区分大小写的文本搜索。始终显示PII警告——摘要是调度员输入的自由文本，可能包含客户姓名或联系信息。最多返回50场比赛。

参数： search_text （必填，至少2个字符）， technician_name （可选）， job_type （可选）， start_date, end_date

______________________________________________________________________

省略时，所有日期参数默认为最后一个完整的周一至周日。最大日期范围为90天。

______________________________________________________________________

日志

服务器将结构化JSON日志写入 logs/mcp_server.log.可用于调试：

# Watch logs in real time (Git Bash / PowerShell)
Get-Content logs\mcp_server.log -Wait -Tail 20

日志从不包含凭据、OAuth令牌或客户个人信息。

______________________________________________________________________

故障排除

服务器未出现在Claude Desktop中

1. 跑 --check 验证凭据是否有效
2. 确认配置文件位于正确的UWP路径中（见上文）
3. 完全退出Claude Desktop（检查任务管理器——它可能仍在后台运行）并重新启动

“没有找到匹配的技术人员…”

名称搜索是不区分大小写的子字符串匹配。尝试一个较短的片段：

• “丹尼R”→ works
• “丹尼”→ works
• “丹尼·罗伊”→ 如果实际名称为“Danny R”，则失败

跑 list_technicians 查看确切的名称。

日期范围错误

• 日期必须在 YYYY-MM-DD 格式
• 最大范围为90天
• 自动默认为上周一至周日

身份验证错误

令牌每15分钟过期一次，但会自动刷新。如果您看到身份验证错误，请检查您的 ST_CLIENT_SECRET 在 .env 是当前的。凭据可能需要在ServiceTitan开发人员门户中轮换。

______________________________________________________________________

添加新工具

看 CLAUDE.project.md → “添加新功能”用于分步过程。

一般模式：

1. 添加新 @mcp.tool() 在适当的情况下发挥作用 tools_*.py 模块
2. 在中添加输入验证 query_validator.py
3. 在中添加共享助手 shared_helpers.py 如有需要
4. 在返回数据之前清除PII
5. 使用新工具更新此README

______________________________________________________________________

安全

• 只读： 服务器只能发出GET请求。POST/PUT/DELETE会立即引发错误。
• PII最小化： 客户姓名、地址、电子邮件和电话号码在处理前从所有API回复中删除。
• 凭证安全： OAuth令牌和秘密永远不会写入日志或返回给用户。
• 输入验证： 在进行任何API调用之前，所有工具输入都要通过Pydantic进行验证。

______________________________________________________________________

发展

# Activate environment
venv\Scripts\activate

# Format code
black .
ruff check --fix .

# Security audit
pip-audit

# Run tests (once tests/ is built)
pytest tests/ -v