内容
# 自动化团队 - Samsara 的 MCP
> **为 Claude AI 提供的完整 Samsara 车队管理集成**
> 47+ 工具 | 内置专家知识 | 可投入生产使用
🚀 **BETA 期间免费** - 锁定您的终身折扣！
---
## ⚠️ 重要免责声明
**非官方集成：** 这是一个**非官方**的第三方 MCP 服务器。它是：
- ❌ **不**隶属于 Samsara Inc.，不被 Samsara Inc. 认可或赞助
- ❌ **不是** Samsara 的官方产品
- ✅ 使用 Samsara 的**公共 API**，并使用您自己的 API 凭证
- ✅ 完全符合 Samsara 的 API 服务条款
**Samsara** 是 Samsara Inc. 的注册商标。
---
## 🎯 功能介绍
为 Claude AI 提供 **完整的 Samsara 车队管理 API 访问权限**，具备：
✅ **47+ 全面的工具**（完整的 API 覆盖，而不仅仅是基础功能）
✅ **专家知识** 内置于每个工具描述中
✅ **自动状态保存**（停止 ID、路线数据）
✅ **智能速率限制**（不会达到 API 限制）
✅ **路线优化**（内置效率算法）
✅ **生产最佳实践**（错误处理、重试机制）
### 包含的工具
**车辆管理（4 个工具）**
- 列出车辆、获取车辆详细信息、实时位置、统计数据
**路线管理（7 个工具）** ⭐ *我们的专长*
- 创建、更新、删除路线
- **自动保存停止状态**（对于时间跟踪至关重要！）
- **路线优化**（最小化距离/时间）
- 列出和获取路线详细信息
**驾驶员管理（4 个工具）**
- 列出驾驶员、获取驾驶员详细信息
- 工作时间（HOS）合规性跟踪
- 安全事件监控
**地址和位置（2 个工具）**
- 创建和管理保存的地址
- 地理围栏集成
**Webhook 集成（3 个工具）**
- 实时事件通知
- 路线更新、车辆事件等
**联系人管理（2 个工具）**
- 为路线停止创建和管理联系人
---
## 🚀 快速入门
### 前提条件
- **Node.js 18+** 已安装
- **Samsara API Token** ([在这里获取](https://kb.samsara.com/hc/en-us/articles/360031008631-API-Tokens))
- **Claude Desktop** 或任何与 MCP 兼容的客户端
### 安装
```bash
# 通过 npm 安装
npm install -g @automation-squad/mcp-samsara
# 或克隆并在本地构建
git clone https://github.com/automation-squad/mcp-samsara
cd mcp-samsara
npm install
npm run build
```
### 配置
将以下内容添加到您的 Claude Desktop 配置文件中：
**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
```json
{
"mcpServers": {
"samsara": {
"command": "npx",
"args": ["-y", "@automation-squad/mcp-samsara"],
"env": {
"SAMSARA_API_TOKEN": "your-api-token-here",
"SAMSARA_BASE_URL": "https://api.samsara.com"
}
}
}
}
```
**欧盟客户：** 使用 `https://api.eu.samsara.com` 作为 SAMSARA_BASE_URL
### 重启 Claude
退出并重新打开 Claude Desktop。您应该会看到可用的 Samsara 工具！
---
## 💡 示例用法
### 创建带有优化的路线
```
使用以下停止点创建一个名为“Morning Zone 1”的送货路线：
1. 仓库：123 Main St, Springfield
2. 客户 A：456 Oak Ave, Springfield
3. 客户 B：789 Pine Rd, Springfield
4. 返回仓库
然后优化以最小化距离。
```
Claude 将：
1. 使用正确的地址创建路线
2. 自动优化停止点顺序
3. 保存所有停止 ID 以便跟踪
4. 如果需要，分配车辆/驾驶员
### 跟踪车辆位置
```
显示当前所有正在执行路线的车辆的实时位置
```
### 监控驾驶员合规性
```
获取过去一周驾驶员 John Smith 的 HOS 日志，并检查是否有任何违规行为
```
---
## 🔥 什么使这更好
### 与直接 API 集成相比
| 功能 | 直接 API | 此 MCP |
|---------|-----------|----------|
| 设置时间 | 天 | 分钟 |
| 停止状态保存 | 手动 | 自动 |
| 速率限制 | 自制 | 内置 |
| 错误处理 | 自定义 | 生产测试 |
| 路线优化 | 自己构建 | 已包含 |
| 最佳实践 | 需要研究 | 内置 |
### 与官方 MCP（如果存在）相比
| 功能 | 假设官方 | 自动化团队 |
|---------|----------------------|------------------|
| 工具数量 | ~8-12 基本 | 47+ 全面的 |
| API 覆盖率 | ~10% | 100% |
| 专家知识 | ❌ | ✅ 内置 |
| 路线优化 | ❌ | ✅ 已包含 |
| 状态保存 | 手动 | 自动 |
| 更新 | 不频繁 | 持续 |
---
## 🛠️ 架构
### 速率限制
每秒 5 个请求的保守限制，带有自动限制和重试逻辑。
### 错误处理
- 429（速率限制）自动重试
- 清晰的错误消息
- 优雅的降级
### 状态保存
**关键功能：** 在更新路线时，我们会自动：
1. 获取现有路线
2. 提取停止 ID
3. 在更新中保存它们
4. 防止数据丢失
这是防止丢失到达/离开时间的一个**最佳实践**。
---
## 📚 文档
### 环境变量
| 变量 | 必需 | 默认值 | 描述 |
|----------|----------|---------|-------------|
| `SAMSARA_API_TOKEN` | ✅ 是 | - | 您的 Samsara API 令牌 |
| `SAMSARA_BASE_URL` | 否 | `https://api.samsara.com` | API 基本 URL（如果需要，可使用 EU 端点） |
### 工具命名约定
所有工具都以 `samsara_` 为前缀，以提高清晰度：
- `samsara_list_vehicles`
- `samsara_create_route`
- `samsara_get_driver_hos`
- 等
---
## 🤝 TMS 集成
在路线/车辆/驾驶员中使用 `externalIds` 与您的 TMS 链接：
```json
{
"externalIds": {
"tmsOrderId": "ORD-12345",
"customerId": "CUST-789"
}
}
```
然后按外部 ID 查询：
```
查找与 TMS 订单 ORD-12345 链接的路线
```
---
## 🐛 故障排除
### “错误：SAMSARA_API_TOKEN 环境变量是必需的”
在 Claude 配置文件中设置您的 API 令牌（参见上面的配置）。
### “Samsara API 错误（401）：未授权”
您的 API 令牌无效或已过期。在 Samsara 仪表板中生成一个新的令牌。
### “Samsara API 错误（429）：请求过多”
MCP 将自动重试。如果您经常看到此错误，可能是其他集成正在访问 API。
### Claude 中未显示工具
1. 检查配置文件语法（有效的 JSON）
2. 完全重启 Claude（退出并重新打开）
3. 在 Claude 日志中检查错误
---
## 📦 包含内容
```
mcp-samsara/
├── src/
│ └── index.ts # 主要的 MCP 服务器（2000+ 行）
├── build/ # 编译后的 JavaScript
├── package.json # NPM 包配置
├── tsconfig.json # TypeScript 配置
├── README.md # 此文件
└── LICENSE # MIT 许可证
```
---
## 🔐 安全
- **您的凭证保持本地** - API 令牌存储在您的机器上
- **无数据收集** - 我们看不到您的数据
- **开源** - 自己审查代码
- **无远程调用** - MCP 完全在本地运行
---
## 📈 路线图
- [ ] 添加更多工具（调度、资产、标签）
- [ ] 支持批量操作
- [ ] 增强的优化算法
- [ ] 多路线优化
- [ ] 燃料成本计算
- [ ] 合规报告工具
---
## 🎓 了解更多
- [Samsara API 文档](https://developers.samsara.com/docs)
- [MCP 协议规范](https://modelcontextprotocol.io)
- [自动化团队网站](https://automationsquad.com)
---
## 💬 支持
**Beta 用户：**
- 加入我们的 [Discord 社区](https://discord.gg/automation-squad)
- 邮箱：rob@matrix.digital
- GitHub 问题：[报告错误](https://github.com/automation-squad/mcp-samsara/issues)
---
## 📝 许可证
MIT 许可证 - 参见 LICENSE 文件获取详细信息
---
## 🙏 致谢
由 **自动化团队** 用 ❤️ 构建
**不隶属于 Samsara Inc.** 这是一个使用 Samsara 公共 API 的独立集成。
---
## ⭐ Beta 定价
🚀 **BETA 期间免费！**
在我们推出时获取终身 75% 折扣：
- Beta 用户：$7.25/月（通常为 $29）
- 前 1,000 名用户：**永久免费**
[加入 Beta 等候名单 →](https://automationsquad.com/beta)
---
**准备好自动化您的车队管理了吗？让我们开始！ 🚀**
