mcp-samsara

# Automation Squad - MCP for Samsara

> **Complete Samsara Fleet Management integration for Claude AI**  
> 21 tools | Expert knowledge built-in | Beta

---

## ⚠️ Important Disclaimer

**UNOFFICIAL INTEGRATION:** This is an **unofficial** third-party MCP server. It is:
- ❌ **NOT** affiliated with, endorsed by, or sponsored by Samsara Inc.
- ❌ **NOT** an official Samsara product
- ✅ Built using Samsara's **public API** with your own API credentials
- ✅ Fully compliant with Samsara's API terms of service

**Samsara®** is a registered trademark of Samsara Inc.

See [NOTICE](NOTICE) for the full third-party disclaimer. Licence: [MIT](LICENSE).

---

## 🎯 What This Does

Connects Claude AI to the Samsara Fleet Management API with:

✅ **21 tools** across vehicles, routes, drivers, addresses, webhooks and contacts  
✅ **Expert knowledge** built into every tool description  
✅ **Automatic state preservation** (stop IDs, route data)  
✅ **Smart rate limiting** (won't hit API limits)  
✅ **Route optimization** (built-in efficiency algorithms)  
✅ **Production best practices** (error handling, retries)

### Tools Included

**Vehicle Management (4 tools)**
- List vehicles, get vehicle details, real-time locations, statistics

**Route Management (6 tools)** ⭐ *Our specialty*
- Create, update, delete routes
- **Auto-preserve stop state** (critical for time tracking!)
- **Route optimization** (minimize distance/time)
- List and get route details

**Driver Management (4 tools)**
- List drivers, get driver details
- Hours of Service (HOS) compliance tracking
- Safety event monitoring

**Address & Location (2 tools)**
- Create and manage saved addresses
- Geofence integration

**Webhook Integration (3 tools)**
- Real-time event notifications
- Route updates, vehicle events, etc.

**Contact Management (2 tools)**
- Create and manage contacts for route stops

---

## 🚀 Quick Start

### Prerequisites

- **Node.js 18+** installed
- **Samsara API Token** ([Get one here](https://kb.samsara.com/hc/en-us/articles/360031008631-API-Tokens))
- **Claude Desktop** or any MCP-compatible client

### Installation

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

> **Note:** the npm package `@automationsquad/mcp-samsara` is not published yet, so
> clone-and-build is the only install path that works today. When it ships, an `npx`
> one-liner will replace the steps above.

### Configuration

Add to your Claude Desktop config file:

**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`  
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

```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"
      }
    }
  }
}
```

Replace `/absolute/path/to/mcp-samsara` with wherever you cloned the repo. The path must
be absolute — Claude Desktop does not resolve `~` or relative paths.

**EU customers:** Use `https://api.eu.samsara.com` for SAMSARA_BASE_URL

### Restart Claude

Quit and reopen Claude Desktop. You should see the Samsara tools available!

---

## 💡 Example Usage

### Create a route with optimization

```
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 will:
1. Create the route with proper addresses
2. Automatically optimize stop order
3. Preserve all stop IDs for tracking
4. Assign vehicle/driver if requested

### Track vehicle locations

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

### Monitor driver compliance

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

---

## 🔥 What Makes This Better

### vs. Building Direct API Integration

| Feature | Direct API | This MCP |
|---------|-----------|----------|
| Setup time | Days | Minutes |
| Stop state preservation | Manual | Automatic |
| Rate limiting | DIY | Built-in |
| Error handling | Custom | Production-tested |
| Route optimization | Build yourself | Included |
| Best practices | Research needed | Built-in |

### vs. Official MCP (if one existed)

| Feature | Hypothetical Official | Automation Squad |
|---------|----------------------|------------------|
| Tool count | ~8-12 basic | 21 |
| API coverage | ~10% | Fleet, routes, drivers, HOS, webhooks |
| Expert knowledge | ❌ | ✅ Built-in |
| Route optimization | ❌ | ✅ Included |
| State preservation | Manual | Automatic |
| Updates | Sporadic | Continuous |

---

## 🛠️ Architecture

### Rate Limiting

Conservative 5 requests/second with automatic throttling and retry logic.

### Error Handling

- Automatic retry on 429 (rate limit)
- Clear error messages
- Graceful degradation

### State Preservation

**Critical feature:** When updating routes, we automatically:
1. Fetch existing route
2. Extract stop IDs
3. Preserve them in updates
4. Prevent data loss

This is a **best practice** that prevents losing arrival/departure times.

---

## 📚 Documentation

### Environment Variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `SAMSARA_API_TOKEN` | ✅ Yes | - | Your Samsara API token |
| `SAMSARA_BASE_URL` | No | `https://api.samsara.com` | API base URL (use EU endpoint if needed) |

### Tool Naming Convention

All tools are prefixed with `samsara_` for clarity:
- `samsara_list_vehicles`
- `samsara_create_route`
- `samsara_get_driver_hos`
- etc.

---

## 🤝 TMS Integration

Use `externalIds` in routes/vehicles/drivers to link with your TMS:

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

Then query by external ID:
```
Find the route linked to TMS order ORD-12345
```

---

## 🐛 Troubleshooting

### "Error: SAMSARA_API_TOKEN environment variable is required"

Set your API token in the Claude config file (see Configuration above).

### "Samsara API error (401): Unauthorized"

Your API token is invalid or expired. Generate a new one in Samsara dashboard.

### "Samsara API error (429): Too Many Requests"

The MCP will automatically retry. If you see this often, you may have other integrations hitting the API.

### Tools not showing in Claude

1. Check config file syntax (valid JSON)
2. Restart Claude completely (quit and reopen)
3. Check Claude logs for errors

---

## 📦 What's Included

```
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
```

---

## 🔐 Security

- **Your credentials stay local** - API token is stored on your machine
- **No data collection** - We don't see your Samsara data
- **Open source** - Review the code yourself
- **No phone-home** - MCP runs entirely locally

---

## 📈 Roadmap

- [ ] Add more tools (dispatch, assets, tags)
- [ ] Support for batch operations
- [ ] Enhanced optimization algorithms
- [ ] Multi-route optimization
- [ ] Fuel cost calculations
- [ ] Compliance reporting tools

---

## 🎓 Learn More

- [Samsara API Documentation](https://developers.samsara.com/docs)
- [MCP Protocol Specification](https://modelcontextprotocol.io)
- [Automation Squad Website](https://automationsquad.com)

---

## 💬 Support

**Beta Users:**
- Join the [Automation Squad community](https://www.skool.com/automationsquad)
- Email: rob@matrix.digital
- GitHub Issues: [Report a bug](https://github.com/AutomationSquadOS/mcp-samsara/issues)

---

## 📝 License

MIT License - See LICENSE file for details

---

## 🙏 Credits

Built with ❤️ by **Automation Squad**

**Not affiliated with Samsara Inc.** This is an independent integration using Samsara's public API.

---

## ⭐ More from Automation Squad

**Docs, install steps and what this server does not do:**
[automationsquad.com/mcp/samsara](https://automationsquad.com/mcp/samsara/)

**The AI Five** — five things worth knowing about AI and automation, weekly.
[Subscribe free →](https://automationsquad.com/newsletter/)

---

**Ready to automate your fleet management? Let's go! 🚀**