内容
# ServiceTitan MCP 服务器
[](https://github.com/montrellcruse/servicetitan-mcp/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/@rowvyn/servicetitan-mcp)
[](LICENSE)
[](https://modelcontextprotocol.io)
[](#工具目录)
[](#工具目录)
ServiceTitan API 的唯一 MCP 服务器 — 15 个领域中的 483 个工具，以及 10 个将原始 API 数据转化为商业决策的智能工具。
由 [**Rowvyn**](https://rowvyn.com) 构建 — [查看案例研究](https://rowvyn.com/case-studies/servicetitan-mcp)
<p align="center">
<em>通过模型上下文协议将任何 AI 助手连接到 ServiceTitan 的完整 API — CRM、调度、发票、工资单和运营智能。</em>
</p>
---
## 为什么
- **ServiceTitan 没有官方的 MCP 服务器** 或开发者工具链，超过 REST 文档
- **原始 API 访问摩擦大** — OAuth 令牌管理、模块前缀路由、分页和响应解析都需要您自己处理
- **此服务器处理所有这些** 并添加了 10 个智能工具，聚合多个端点以获得运营洞察
- **仪表板匹配的收入** — 使用与 ST 自己的仪表板相同的报告 API 源验证生产数据
---
## 功能
- **15 个领域中的 483 个工具** — CRM、调度、会计、工资单、库存、营销等
- **10 个智能工具** — 复合分析，聚合多个 API 调用以获得收入摘要、运营快照、技术人员记分卡等
- **仪表板匹配的收入** — `intel_revenue_summary` 从与 ST 自己的仪表板相同的源获取
- **默认只读** — `ST_READONLY=true` 开箱即用；仅在您准备好时激活写入工具
- **安全层** — 写入/删除的确认工作流，审计日志和敏感字段红名
- **领域过滤** — 通过 `ST_DOMAINS` 仅公开您需要的工具组
- **基于名称的过滤** — 传递 `businessUnitName` 或 `technicianName` 而不是数字 ID；通过 30 分钟缓存解析
- **LLM 优化的响应** — 响应塑形修剪 API 噪音并为 AI 消费结构化数据
- **可流式 HTTP 远程部署** — 部署到 Fly.io（或任何地方）并通过 `mcp-remote` 连接
- **内置健康检查** — `st_health_check` 验证身份验证和租户访问（不暴露配置详细信息）
---
## 快速开始
### 先决条件
- Node.js 22 或更新版本
- ServiceTitan API 凭证：客户端 ID、客户端密钥、应用密钥、租户 ID
### npx（推荐）
无需安装 — 直接运行：
```json
{
"mcpServers": {
"servicetitan": {
"command": "npx",
"args": ["-y", "@rowvyn/servicetitan-mcp"],
"env": {
"ST_CLIENT_ID": "您的客户端 ID",
"ST_CLIENT_SECRET": "您的客户端密钥",
"ST_APP_KEY": "您的应用密钥",
"ST_TENANT_ID": "您的租户 ID",
"ST_ENVIRONMENT": "生产环境"
}
}
}
}
```
> ⚠️ **`ST_ENVIRONMENT` 默认值为 `integration`.** 如果您连接到实时 ServiceTitan 账户，您 **必须** 将 `ST_ENVIRONMENT` 设置为 `production`，否则您将遇到静默身份验证失败和空结果。
### 全局安装
```bash
npm install -g @rowvyn/servicetitan-mcp
servicetitan-mcp # stdio 传输（适用于 Claude Desktop）
servicetitan-mcp-sse # SSE 传输（旧版远程）
servicetitan-mcp-http # 流式 HTTP 传输（推荐远程）
```
### 从源代码构建
```bash
npm install
npm run build
```
### Claude Desktop
对于本地检出，在构建的 stdio 入口处指向 Claude Desktop：
将以下内容添加到您的 `claude_desktop_config.json` 中：
```json
{
"mcpServers": {
"servicetitan": {
"command": "node",
"args": ["/绝对路径/to/servicetitan-mcp/build/index.js"],
"env": {
"ST_CLIENT_ID": "您的客户端 ID",
"ST_CLIENT_SECRET": "您的客户端密钥",
"ST_APP_KEY": "您的应用密钥",
"ST_TENANT_ID": "您的租户 ID",
"ST_TIMEZONE": "America/New_York"
}
}
}
}
```
与其他 MCP 兼容的主机（如 **Cursor**、**Windsurf**）的工作方式相同。
### 通用_stdio_
```bash
ST_CLIENT_ID=您的客户端ID \
ST_CLIENT_SECRET=您的客户端密钥 \
ST_APP_KEY=您的应用密钥 \
ST_TENANT_ID=您的租户ID \
ST_TIMEZONE=America/New_York \
node /绝对路径/to/servicetitan-mcp/build/index.js
```
### 远程部署（流式 HTTP）
部署到 Fly.io 或任何服务器，然后通过 `mcp-remote` 连接：
```bash
# 在服务器上
ST_CLIENT_ID=... ST_CLIENT_SECRET=... ST_APP_KEY=... ST_TENANT_ID=... \
ST_MCP_API_KEY=您的密钥 node build/streamable-http.js
```
```json
{
"mcpServers": {
"servicetitan": {
"command": "npx",
"args": [
"mcp-remote",
"https://您的实例.fly.dev/mcp",
"--header",
"x-api-key: 您的MCP_API_KEY"
]
}
}
}
```
> SSE 仍然在 `build/sse.js` 中可用以保持向后兼容，但已弃用。对于新部署，请在 `/mcp` 处首选流式 HTTP。
---
## 工具目录
15 个领域中注册了 483 个工具：
| 领域 | 工具 | 示例工具 |
|--------|------:|---------------|
| `dispatch` | 79 | `dispatch_jobs_list`, `dispatch_appointments_get`, `dispatch_job_types_list` |
| `crm` | 71 | `crm_customers_list`, `crm_contacts_get`, `crm_bookings_create` |
| `export` | 49 | `export_invoices`, `export_customers`, `export_jobs` |
| `inventory` | 37 | `inventory_purchase_orders_list`, `inventory_vendors_list`, `inventory_warehouses_list` |
| `marketing` | 35 | `marketing_campaigns_list`, `marketing_calls_v3_list`, `marketing_reviews` |
| `accounting` | 33 | `accounting_invoices_list`, `accounting_payments_list`, `accounting_gl_accounts_list` |
| `pricebook` | 31 | `pricebook_services_list`, `pricebook_materials_list`, `pricebook_equipment_list` |
| `payroll` | 27 | `payroll_payrolls_list`, `payroll_timesheets_job_list`, `payroll_gross_pay_items_list` |
| `settings` | 23 | `settings_business_units_list`, `settings_tag_types_list`, `settings_user_roles_list` |
| `people` | 22 | `people_technicians_list`, `people_employees_list`, `people_trucks_list` |
| `memberships` | 21 | `memberships_list`, `memberships_types_list`, `memberships_recurring_services_list` |
| `scheduling` | 17 | `scheduling_teams_list`, `scheduling_zones_list`, `scheduling_capacity_calculate` |
| `estimates` | 22 | `estimates_list`, `estimates_get`, `estimates_items_list` |
| **`intelligence`** | **10** | `intel_revenue_summary`, `intel_daily_snapshot`, `intel_technician_scorecard` |
| `reporting` | 5 | `reporting_reports_list`, `reporting_report_categories_list` |
| **总数** | **482** | *(+ 1 系统工具：`st_health_check` = **483** 总计)* |
> 在 `ST_READONLY=true`（默认）下，所有工具都已注册，但写入和删除操作在执行时会被阻止，并显示清晰的错误消息。使用 `ST_CONFIRM_WRITES=true` 需要在写入操作中添加 `_confirmed: true`，或在删除操作中添加 `confirm: true`。
---
## 智能工具
真正的差异所在。这些 10 个工具聚合多个 API 调用和报告端点以获得运营洞察 — 这些洞察通常需要自定义 BI 工具。
| 工具 | 返回内容 |
|------|----------------|
| `intel_revenue_summary` | 业务单元的仪表板匹配收入。包括已完成的收入、非作业收入、调整、收款和业务单元生产力汇总。 |
| `intel_daily_snapshot` | 6 项指标的当日运营简报：当日收入、正在进行的作业、通话结果、预订、开放估算和明日作业安排。 |
| `intel_technician_scorecard` | 每位技术人员的作业、收入、平均票价、生产力、潜在客户生成、会员关闭率和销售业绩 — 包括团队平均值。 |
| `intel_membership_health` | 活跃会员、注册、取消、续期、留存率、已开票收入和业务单元转换率。 |
| `intel_estimate_pipeline` | 开放/已售/已驳回的漏斗、转换率、关闭时间、天数、陈旧机会和技术人员销售漏斗指标。 |
| `intel_campaign_performance` | 活动调用、预订、转换率、总收入上下文和业务单元潜在客户生成指标。 |
| `intel_csr_performance` | CSR 预订性能：预订作业、收入、平均票价、顶级活动、作业类型组合、转换指标和团队平均值。 |
| `intel_labor_cost` | 来自主支付文件的劳动成本汇总：员工小时数、总工资、小时费率、活动组合和业务单元分解。 |
| `intel_invoice_tracking` | 发票电子邮件跟踪：发送 vs 未发送计数、发送率、美元影响和业务单元和技术人员未发送的分解。 |
| `intel_lookup` | 缓存的参考数据 — 技术人员、业务单元、付款类型、会员类型，附带 ID 和名称。 30 分钟 TTL。 |
这些工具是此服务器存在的原因。原始 CRUD 工具是基本要求。智能工具将 API 数据转化为商业决策。
### 收入准确性
`intel_revenue_summary` 使用 ServiceTitan 的 **报告 API** 计算总额。这是 ST 自身仪表板使用的相同源，这意味着它包括：
- **已完成收入** — 来自已完成作业的收入
- **非作业收入** — 会员费、附加项和其他与特定作业无关的收入
- **调整收入** — 信用额度、调整和更正
原始发票或作业端点总和不匹配仪表板。两者都缺少非作业收入。要获得仪表板匹配的数字，请使用 `intel_revenue_summary`。对于发票级详细信息，请使用 `accounting_invoices_list`。
### 基于名称的过滤
大多数智能工具接受 `businessUnitName` 和 `technicianName` 作为数字 ID 的替代：
```bash
# 而不是：
intel_revenue_summary(startDate="2026-01-01", endDate="2026-04-01", businessUnitId=12345)
# 使用：
intel_revenue_summary(startDate="2026-01-01", endDate="2026-04-01", businessUnitName="HVAC")
```
业务单元名称匹配使用精确 → 前缀 → 包含的 fallback。技术人员名称匹配使用不区分大小写的子字符串搜索。如果找不到匹配项，该工具会返回所有数据并带有警告。
---
## 配置
复制 `.env.example` 到 `.env` 并填写您的凭证。
**必填**
| 变量 | 描述 |
|----------|-------------|
| `ST_CLIENT_ID` | ServiceTitan OAuth 客户端 ID |
| `ST_CLIENT_SECRET` | ServiceTitan OAuth 客户端密钥 |
| `ST_APP_KEY` | ServiceTitan 应用密钥 (`ST-App-Key` 头部) |
| `ST_TENANT_ID` | ServiceTitan 租户标识符 |
| `ST_MCP_API_KEY` | 远程 MCP 客户端的 API 密钥 *(远程 HTTP 部署必填)* |
**可选**
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `ST_ENVIRONMENT` | `integration` | ServiceTitan 环境：`integration` 或 `production` |
| `ST_READONLY` | `true` | 在执行时阻止写入和删除操作 |
| `ST_CONFIRM_WRITES` | `false` | 需要 `_confirmed: true` 来执行写入工具 |
| `ST_MAX_RESPONSE_CHARS` | `100000` | 限制工具响应大小 |
| `ST_DOMAINS` | *(所有)* | 用逗号分隔的域名允许列表（例如 `crm,dispatch,reporting`） |
| `ST_LOG_LEVEL` | `info` | 日志级别：`debug`, `info`, `warn`, `error` |
| `ST_TIMEZONE` | `UTC` | 租户的 IANA 时区（例如 `America/New_York`）— 用于日期界限智能查询和所有工具响应中的本地时间显示转换 |
| `ST_RESPONSE_SHAPING` | `true` | 设置为 `false` 以禁用智能响应转换 |
| `ST_CORS_ORIGIN` | _(无)_ | 流式 HTTP / SSE 的允许 CORS 源。浏览器访问必填。 |
| `ST_ALLOWED_CALLERS` | _(无)_ | 用逗号分隔的调用者身份允许列表（例如 `alice@example.com,svc-user`) |
| `ST_INTEL_CACHE_TTL_MS` | `300000` | 智能结果缓存 TTL（毫秒，默认：5 分钟） |
| `ST_MCP_PORT` / `PORT` | `3100` | Streamable HTTP 和 SSE 传输的 HTTP 服务器端口 |
> **设置 `ST_TIMEZONE`** 为您的租户的本地时区。没有它，日期查询（例如 `startDate: "2026-02-01"`）被解释为 UTC 午夜 — 这可能会错过或包含非 UTC 租户的发票和作业边界，并且工具响应将保持 UTC 而不是您的本地显示时区。
布尔环境变量接受：`true`, `false`, `1`, `0`（不区分大小写）。
---
## 架构
服务器构建为分层系统：**配置 → OAuth 客户端 → 域注册 → MCP 服务器**。
- **域模块模式** — 每个域位于 `src/domains/<domain>/` 并导出一个加载器来注册其工具
- **动态发现** — `src/domains/loader.ts` 扫描 `src/domains/*/index.ts` 并在运行时导入每个域
- **中央注册** — `ToolRegistry` 处理域名过滤、只读强制、确认包装和审计日志
- **OAuth 客户端** — `ServiceTitanClient` 管理客户端凭证身份验证、令牌刷新、重试-401/429 和 `{tenant}` 路径注入
- **响应塑形** — 转换层剥离 API 噪音并为 LLM 消费结构化数据
- **智能层** — 复合工具发出多个端点和报告 ID，然后聚合结果
查看 [ARCHITECTURE.md](ARCHITECTURE.md) 以获取完整的深入了解：路由表、响应塑形管道、智能层设计和安全系统。
---
## CLI 伴侣
如果您更喜欢直接从终端操作，[servicetitan-cli](https://github.com/montrellcruse/servicetitan-cli) 是从相同的身份验证和智能层构建的 `st` 二进制文件：```bash
# 安装
npm install -g @rowvyn/servicetitan-cli
# 相同的智能 - 不需要 MCP
st revenue --period ytd --compact
st snapshot --compact
# 管道到您的代理
st customers list --all --json | 您的代理进程
```
CLI 和此 MCP 服务器共享相同的设计理念：将业务问题推入工具名称、最小化模式开销并为 AI 消费塑形响应。
---
## 比较
| 功能 | 此服务器 | 社区 MCP 服务器 |
|---------|------------|----------------------|
| 收入准确性 | ✅ 仪表板匹配 | ❌ $17–21K 每个期间不准确 |
| 智能工具 | ✅ 10 个工具 | ❌ 无 |
| 领域覆盖 | ✅ 483 个工具，15 个领域 | ⚠️ 10–50 个工具 |
| 安全层 | ✅ 默认只读，审计日志 | ❌ 无 |
| 响应塑形 | ✅ 针对 LLM 优化 | ❌ 原始 API 响应 |
| 基于名称的过滤 | ✅ 自动解析名称为 ID | ❌ 需要数字 ID |
| 远程部署 | ✅ 流式 HTTP + `mcp-remote` | ⚠️ 变化 |
| | | |
---
## 开发
```bash
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
```
---
## 安全
- **只读模式** (`ST_READONLY=true` 默认) — 所有工具都已注册，但在执行时阻止写入和删除操作
- **确认工作流** — 删除工具需要 `confirm: true`（缺少时返回预览有效载荷）；写入工具可选地需要 `_confirmed: true` 通过 `ST_CONFIRM_WRITES=true`（缺少时返回错误）
- **审计日志** — 所有写入/删除执行都会发出 `[AUDIT]` 日志记录，带有时间戳、工具、操作、资源和清理参数（机密/令牌被涂黑）
---
## 故障排除
### npm 权限错误（EACCES）
如果您看到 `EACCES: permission denied` 错误，当 Claude Desktop 尝试启动服务器时，您的 npm 缓存目录可能由 root 所有（常见于 Node 通过 `sudo` 安装时）。
**修复：**
```bash
sudo chown -R $(whoami) ~/.npm
```
然后重新启动 Claude Desktop。
### 服务器无法启动 / “无法连接到 MCP 服务器”
1. **在 Claude Desktop 之外进行测试：**
```bash
npx -y @rowvyn/servicetitan-mcp
```
如果失败，则问题出在 Node、npm 或您的环境中 — 而不是 Claude Desktop。
2. **检查 Node 版本：** `node -v` — 需要 Node 22 或更新版本。
3. **检查冲突的 MCP 安装：** 如果您之前安装了不同的 ServiceTitan MCP 服务器，请删除它：
```bash
npm ls -g --depth=0 | grep -i servicetitan
npm uninstall -g <old-package-name>
npx clear-npx-cache
```
4. **验证您的 `claude_desktop_config.json`** 没有来自以前的 MCP 服务器的遗留条目。只有一个 `servicetitan` 条目应存在于 `mcpServers` 下。
### 身份验证失败 / $0 收入 / 空结果
- **设置 `ST_ENVIRONMENT` 为 `production`。** 这是 #1 原因。默认值为 `integration`，它会验证 ServiceTitan 的沙盒 — 而不是您的实时帐户。您将获得有效的身份验证令牌，但返回的数据为零。
- **验证凭证是否匹配：** `ST_CLIENT_ID` 和 `ST_CLIENT_SECRET` 必须来自同一个 ServiceTitan 应用程序。您不能混合使用不同应用程序的凭证。
- **检查 `ST_TENANT_ID`:** 必须与 ServiceTitan 开发者门户中的应用程序关联的租户匹配。
### Claude Desktop 日志
Claude Desktop 将 MCP 服务器日志写入：
- **macOS:** `~/Library/Logs/Claude/mcp*.log`
- **Windows:** `%APPDATA%\Claude\logs\mcp*.log`
---
## 贡献
详见 [CONTRIBUTING.md](CONTRIBUTING.md)。
---
## 安全
详见 [SECURITY.md](SECURITY.md) 以获取漏洞披露政策。
---
## 许可证
MIT 许可证
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器