Samsara MCP

Automation Squad - Samsara 的 MCP

为 Claude AI 提供完整的 Samsara 车队管理集成
21 个工具 | 内置专业知识 | Beta

---

⚠️ 重要免责声明

非官方集成： 这是一个非官方第三方 MCP 服务。它：

• ❌ 未与 Samsara Inc. 建立关联，也未获得其认可或赞助
• ❌ 不是 Samsara 的官方产品
• ✅ 使用你自己的 API 凭据，通过 Samsara 的公共 API构建
• ✅ 完全符合 Samsara 的 API 服务条款

Samsara® 是 Samsara Inc. 的注册商标。

完整的第三方免责声明请参阅 NOTICE。许可协议：MIT。

---

🎯 功能介绍

将 Claude AI 连接到 Samsara 车队管理 API，提供：

✅ 覆盖车辆、路线、驾驶员、地址、Webhook 和联系人的 21 个工具
✅ 每个工具的说明中都内置了专业知识
✅ 自动保留状态（停靠点 ID、路线数据）
✅ 智能速率限制（不会触及 API 限额）
✅ 路线优化（内置效率算法）
✅ 生产环境最佳实践（错误处理、重试）

包含的工具

车辆管理（4 个工具）

• 列出车辆、获取车辆详情、实时位置和统计数据

路线管理（6 个工具） ⭐ 我们的专长

• 创建、更新和删除路线
• 自动保留停靠点状态（对时间跟踪至关重要！）
• 路线优化（缩短距离/时间）
• 列出并获取路线详情

驾驶员管理（4 个工具）

• 列出驾驶员、获取驾驶员详情
• 服务时长（HOS）合规跟踪
• 安全事件监控

地址和位置（2 个工具）

• 创建和管理已保存的地址
• 地理围栏集成

Webhook 集成（3 个工具）

• 实时事件通知
• 路线更新、车辆事件等

联系人管理（2 个工具）

• 创建和管理路线停靠点联系人

---

🚀 快速开始

前置条件

• 已安装 Node.js 18+
• Samsara API 令牌（在此获取）
• Claude Desktop 或任何兼容 MCP 的客户端

安装

git clone https://github.com/AutomationSquadOS/mcp-samsara
cd mcp-samsara
npm install
npm run build

注意： npm 包 @automationsquad/mcp-samsara 尚未发布，因此目前只能通过克隆并构建来安装。该包发布后，上述步骤将由一条 npx 命令取代。

配置

添加到 Claude Desktop 配置文件：

macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
Windows： %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "samsara": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-samsara/build/index.js"],
      "env": {
        "SAMSARA_API_TOKEN": "your-api-token-here",
        "SAMSARA_BASE_URL": "https://api.samsara.com"
      }
    }
  }
}

将 /absolute/path/to/mcp-samsara 替换为你克隆仓库的位置。路径必须是绝对路径——Claude Desktop 不会解析 ~ 或相对路径。

欧盟客户： 将 SAMSARA_BASE_URL 设置为 https://api.eu.samsara.com

重启 Claude

退出并重新打开 Claude Desktop。现在应该就能看到可用的 Samsara 工具了！

---

💡 使用示例

创建并优化路线

Create a delivery route called "Morning Zone 1" with these stops:
1. Warehouse: 123 Main St, Springfield
2. Customer A: 456 Oak Ave, Springfield  
3. Customer B: 789 Pine Rd, Springfield
4. Return to warehouse

Then optimize it for minimum distance.

Claude 将：

1. 使用正确的地址创建路线
2. 自动优化停靠点顺序
3. 保留所有停靠点 ID 以供跟踪
4. 按需分配车辆/驾驶员

跟踪车辆位置

Show me real-time locations for all vehicles currently on routes

监控驾驶员合规情况

Get HOS logs for driver John Smith for the past week and check for any violations

---

🔥 优势

与直接构建 API 集成相比

功能	直接 API	此 MCP
设置时间	数天	数分钟
停靠点状态保留	手动	自动
速率限制	自行实现	内置
错误处理	自定义	经过生产环境验证
路线优化	自行构建	内置
最佳实践	需要自行研究	内置

与官方 MCP（假设存在）对比

功能	假设的官方版本	Automation Squad
工具数量	约 8-12 个基础工具	21 个
API 覆盖范围	约 10%	车队、路线、驾驶员、HOS、webhook
专家知识	❌	✅ 内置
路线优化	❌	✅ 已包含
状态保留	手动	自动
更新	偶尔	持续

---

🛠️ 架构

速率限制

保守限制为每秒 5 个请求，并提供自动限流和重试逻辑。

错误处理

• 遇到 429（速率限制）时自动重试
• 清晰的错误消息
• 优雅降级

状态保留

关键功能： 更新路线时，我们会自动：

1. 获取现有路线
2. 提取站点 ID
3. 在更新中保留这些 ID
4. 防止数据丢失

这是一项最佳实践，可防止到达和出发时间丢失。

---

📚 文档

环境变量

变量	必填	默认值	说明
SAMSARA_API_TOKEN	✅ 是	-	您的 Samsara API 令牌
SAMSARA_BASE_URL	否	https://api.samsara.com	API 基础 URL（如有需要，请使用欧盟端点）

工具命名约定

所有工具都以 samsara_ 为前缀，以便识别：

• samsara_list_vehicles
• samsara_create_route
• samsara_get_driver_hos
• 等等

---

🤝 TMS 集成

在路线／车辆／驾驶员中使用 externalIds，以便与您的 TMS 关联：

{
  "externalIds": {
    "tmsOrderId": "ORD-12345",
    "customerId": "CUST-789"
  }
}

然后按外部 ID 查询：

Find the route linked to TMS order ORD-12345

---

🐛 故障排除

“Error: SAMSARA_API_TOKEN environment variable is required”

在 Claude 配置文件中设置您的 API 令牌（参见上文的配置部分）。

“Samsara API error (401): Unauthorized”

您的 API 令牌无效或已过期。请在 Samsara 控制面板中生成新令牌。

“Samsara API error (429): Too Many Requests”

MCP 会自动重试。如果经常遇到此问题，可能是其他集成正在调用该 API。

Claude 中未显示工具

1. 检查配置文件语法（有效的 JSON）
2. 完全重启 Claude（退出并重新打开）
3. 检查 Claude 日志中的错误

---

📦 包含内容

mcp-samsara/
├── src/
│   └── index.ts          # Main MCP server
├── build/                # Compiled JavaScript
├── package.json          # NPM package config
├── tsconfig.json         # TypeScript config
├── README.md            # This file
└── LICENSE              # MIT License

---

🔐 安全性

• 您的凭据保留在本地——API 令牌存储在您的设备上
• 不收集数据——我们无法查看您的 Samsara 数据
• 开源——您可以自行检查代码
• 不向外发送信息——MCP 完全在本地运行

---

📈 路线图

• 添加更多工具（调度、资产、标签）
• 支持批量操作
• 增强优化算法
• 多路线优化
• 燃油成本计算
• 合规报告工具

---

🎓 了解更多

• Samsara API 文档
• MCP 协议规范
• Automation Squad 网站

---

💬 支持

Beta 用户：

• 加入 Automation Squad 社区
• 电子邮件：[email protected]
• GitHub Issues：报告错误

---

📝 许可证

MIT 许可证——详情请参阅 LICENSE 文件

---

🙏 致谢

由 Automation Squad 倾心打造 ❤️

与 Samsara Inc. 无关联。 这是一个使用 Samsara 公共 API 的独立集成。

---

⭐ Automation Squad 的更多内容

文档、安装步骤以及此服务不提供的功能： automationsquad.com/mcp/samsara

The AI Five——每周分享五件值得了解的 AI 与自动化相关内容。 免费订阅 →

---

准备好自动化管理您的车队了吗？开始吧！🚀