MCP 服务器

mcp-samsara

Fleet management in your assistant — vehicles, routes, drivers and HOS compliance over Samsara's public API.

README

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 for the full third-party disclaimer. Licence: MIT.

🎯 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)
Claude Desktop or any MCP-compatible client

Installation

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

{
  "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:

Create the route with proper addresses
Automatically optimize stop order
Preserve all stop IDs for tracking
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:

Fetch existing route
Extract stop IDs
Preserve them in updates
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:

{
  "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

Check config file syntax (valid JSON)
Restart Claude completely (quit and reopen)
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