{
  "markdown": "# Automation Squad - MCP for Samsara\n\n> **Complete Samsara Fleet Management integration for Claude AI**  \n> 21 tools | Expert knowledge built-in | Beta\n\n---\n\n## ⚠️ Important Disclaimer\n\n**UNOFFICIAL INTEGRATION:** This is an **unofficial** third-party MCP server. It is:\n- ❌ **NOT** affiliated with, endorsed by, or sponsored by Samsara Inc.\n- ❌ **NOT** an official Samsara product\n- ✅ Built using Samsara's **public API** with your own API credentials\n- ✅ Fully compliant with Samsara's API terms of service\n\n**Samsara®** is a registered trademark of Samsara Inc.\n\nSee [NOTICE](NOTICE) for the full third-party disclaimer. Licence: [MIT](LICENSE).\n\n---\n\n## 🎯 What This Does\n\nConnects Claude AI to the Samsara Fleet Management API with:\n\n✅ **21 tools** across vehicles, routes, drivers, addresses, webhooks and contacts  \n✅ **Expert knowledge** built into every tool description  \n✅ **Automatic state preservation** (stop IDs, route data)  \n✅ **Smart rate limiting** (won't hit API limits)  \n✅ **Route optimization** (built-in efficiency algorithms)  \n✅ **Production best practices** (error handling, retries)\n\n### Tools Included\n\n**Vehicle Management (4 tools)**\n- List vehicles, get vehicle details, real-time locations, statistics\n\n**Route Management (6 tools)** ⭐ *Our specialty*\n- Create, update, delete routes\n- **Auto-preserve stop state** (critical for time tracking!)\n- **Route optimization** (minimize distance/time)\n- List and get route details\n\n**Driver Management (4 tools)**\n- List drivers, get driver details\n- Hours of Service (HOS) compliance tracking\n- Safety event monitoring\n\n**Address & Location (2 tools)**\n- Create and manage saved addresses\n- Geofence integration\n\n**Webhook Integration (3 tools)**\n- Real-time event notifications\n- Route updates, vehicle events, etc.\n\n**Contact Management (2 tools)**\n- Create and manage contacts for route stops\n\n---\n\n## 🚀 Quick Start\n\n### Prerequisites\n\n- **Node.js 18+** installed\n- **Samsara API Token** ([Get one here](https://kb.samsara.com/hc/en-us/articles/360031008631-API-Tokens))\n- **Claude Desktop** or any MCP-compatible client\n\n### Installation\n\n```bash\ngit clone https://github.com/AutomationSquadOS/mcp-samsara\ncd mcp-samsara\nnpm install\nnpm run build\n```\n\n> **Note:** the npm package `@automationsquad/mcp-samsara` is not published yet, so\n> clone-and-build is the only install path that works today. When it ships, an `npx`\n> one-liner will replace the steps above.\n\n### Configuration\n\nAdd to your Claude Desktop config file:\n\n**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`  \n**Windows:** `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"samsara\": {\n      \"command\": \"node\",\n      \"args\": [\"/absolute/path/to/mcp-samsara/build/index.js\"],\n      \"env\": {\n        \"SAMSARA_API_TOKEN\": \"your-api-token-here\",\n        \"SAMSARA_BASE_URL\": \"https://api.samsara.com\"\n      }\n    }\n  }\n}\n```\n\nReplace `/absolute/path/to/mcp-samsara` with wherever you cloned the repo. The path must\nbe absolute — Claude Desktop does not resolve `~` or relative paths.\n\n**EU customers:** Use `https://api.eu.samsara.com` for SAMSARA_BASE_URL\n\n### Restart Claude\n\nQuit and reopen Claude Desktop. You should see the Samsara tools available!\n\n---\n\n## 💡 Example Usage\n\n### Create a route with optimization\n\n```\nCreate a delivery route called \"Morning Zone 1\" with these stops:\n1. Warehouse: 123 Main St, Springfield\n2. Customer A: 456 Oak Ave, Springfield  \n3. Customer B: 789 Pine Rd, Springfield\n4. Return to warehouse\n\nThen optimize it for minimum distance.\n```\n\nClaude will:\n1. Create the route with proper addresses\n2. Automatically optimize stop order\n3. Preserve all stop IDs for tracking\n4. Assign vehicle/driver if requested\n\n### Track vehicle locations\n\n```\nShow me real-time locations for all vehicles currently on routes\n```\n\n### Monitor driver compliance\n\n```\nGet HOS logs for driver John Smith for the past week and check for any violations\n```\n\n---\n\n## 🔥 What Makes This Better\n\n### vs. Building Direct API Integration\n\n| Feature | Direct API | This MCP |\n|---------|-----------|----------|\n| Setup time | Days | Minutes |\n| Stop state preservation | Manual | Automatic |\n| Rate limiting | DIY | Built-in |\n| Error handling | Custom | Production-tested |\n| Route optimization | Build yourself | Included |\n| Best practices | Research needed | Built-in |\n\n### vs. Official MCP (if one existed)\n\n| Feature | Hypothetical Official | Automation Squad |\n|---------|----------------------|------------------|\n| Tool count | ~8-12 basic | 21 |\n| API coverage | ~10% | Fleet, routes, drivers, HOS, webhooks |\n| Expert knowledge | ❌ | ✅ Built-in |\n| Route optimization | ❌ | ✅ Included |\n| State preservation | Manual | Automatic |\n| Updates | Sporadic | Continuous |\n\n---\n\n## 🛠️ Architecture\n\n### Rate Limiting\n\nConservative 5 requests/second with automatic throttling and retry logic.\n\n### Error Handling\n\n- Automatic retry on 429 (rate limit)\n- Clear error messages\n- Graceful degradation\n\n### State Preservation\n\n**Critical feature:** When updating routes, we automatically:\n1. Fetch existing route\n2. Extract stop IDs\n3. Preserve them in updates\n4. Prevent data loss\n\nThis is a **best practice** that prevents losing arrival/departure times.\n\n---\n\n## 📚 Documentation\n\n### Environment Variables\n\n| Variable | Required | Default | Description |\n|----------|----------|---------|-------------|\n| `SAMSARA_API_TOKEN` | ✅ Yes | - | Your Samsara API token |\n| `SAMSARA_BASE_URL` | No | `https://api.samsara.com` | API base URL (use EU endpoint if needed) |\n\n### Tool Naming Convention\n\nAll tools are prefixed with `samsara_` for clarity:\n- `samsara_list_vehicles`\n- `samsara_create_route`\n- `samsara_get_driver_hos`\n- etc.\n\n---\n\n## 🤝 TMS Integration\n\nUse `externalIds` in routes/vehicles/drivers to link with your TMS:\n\n```json\n{\n  \"externalIds\": {\n    \"tmsOrderId\": \"ORD-12345\",\n    \"customerId\": \"CUST-789\"\n  }\n}\n```\n\nThen query by external ID:\n```\nFind the route linked to TMS order ORD-12345\n```\n\n---\n\n## 🐛 Troubleshooting\n\n### \"Error: SAMSARA_API_TOKEN environment variable is required\"\n\nSet your API token in the Claude config file (see Configuration above).\n\n### \"Samsara API error (401): Unauthorized\"\n\nYour API token is invalid or expired. Generate a new one in Samsara dashboard.\n\n### \"Samsara API error (429): Too Many Requests\"\n\nThe MCP will automatically retry. If you see this often, you may have other integrations hitting the API.\n\n### Tools not showing in Claude\n\n1. Check config file syntax (valid JSON)\n2. Restart Claude completely (quit and reopen)\n3. Check Claude logs for errors\n\n---\n\n## 📦 What's Included\n\n```\nmcp-samsara/\n├── src/\n│   └── index.ts          # Main MCP server\n├── build/                # Compiled JavaScript\n├── package.json          # NPM package config\n├── tsconfig.json         # TypeScript config\n├── README.md            # This file\n└── LICENSE              # MIT License\n```\n\n---\n\n## 🔐 Security\n\n- **Your credentials stay local** - API token is stored on your machine\n- **No data collection** - We don't see your Samsara data\n- **Open source** - Review the code yourself\n- **No phone-home** - MCP runs entirely locally\n\n---\n\n## 📈 Roadmap\n\n- [ ] Add more tools (dispatch, assets, tags)\n- [ ] Support for batch operations\n- [ ] Enhanced optimization algorithms\n- [ ] Multi-route optimization\n- [ ] Fuel cost calculations\n- [ ] Compliance reporting tools\n\n---\n\n## 🎓 Learn More\n\n- [Samsara API Documentation](https://developers.samsara.com/docs)\n- [MCP Protocol Specification](https://modelcontextprotocol.io)\n- [Automation Squad Website](https://automationsquad.com)\n\n---\n\n## 💬 Support\n\n**Beta Users:**\n- Join the [Automation Squad community](https://www.skool.com/automationsquad)\n- Email: rob@matrix.digital\n- GitHub Issues: [Report a bug](https://github.com/AutomationSquadOS/mcp-samsara/issues)\n\n---\n\n## 📝 License\n\nMIT License - See LICENSE file for details\n\n---\n\n## 🙏 Credits\n\nBuilt with ❤️ by **Automation Squad**\n\n**Not affiliated with Samsara Inc.** This is an independent integration using Samsara's public API.\n\n---\n\n## ⭐ More from Automation Squad\n\n**Docs, install steps and what this server does not do:**\n[automationsquad.com/mcp/samsara](https://automationsquad.com/mcp/samsara/)\n\n**The AI Five** — five things worth knowing about AI and automation, weekly.\n[Subscribe free →](https://automationsquad.com/newsletter/)\n\n---\n\n**Ready to automate your fleet management? Let's go! 🚀**\n",
  "bytes": 8466,
  "sha": "e2dfde53956526cb266d15a7a22ee69e9522c5d4a64022e71102d8c47976c15c",
  "repo_slug": "automationsquados/mcp-samsara",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_automationsquados_mcp_samsara_45769257/readme"
}