mcp-samsara
Automation Squad - Samsara용 MCP
Claude AI를 위한 완벽한 Samsara 차량 관리 통합
21개 도구 | 내장된 전문 지식 | 베타
🚀 베타 기간 동안 무료 - 평생 할인 혜택을 지금 확보하세요!
⚠️ 중요 고지사항
비공식 통합: 이는 비공식 타사 MCP 서버입니다. 다음 사항을 숙지하세요:
❌ Samsara Inc.와 제휴, 보증 또는 후원을 받지 않습니다.
❌ 공식 Samsara 제품이 아닙니다.
✅ 자체 API 자격 증명을 사용하여 Samsara의 공개 API를 기반으로 구축되었습니다.
✅ Samsara의 API 이용 약관을 완전히 준수합니다.
**Samsara®**는 Samsara Inc.의 등록 상표입니다.
Related MCP server: Samsara Fleet MCP Server
🎯 기능
Claude AI를 Samsara 차량 관리 API에 연결합니다:
✅ 21개 도구 - 차량, 경로, 운전자, 주소, 웹훅 및 연락처 관리
✅ 전문 지식이 각 도구 설명에 내장됨
✅ 자동 상태 보존 (정류장 ID, 경로 데이터)
✅ 스마트 속도 제한 (API 한도에 도달하지 않음)
✅ 경로 최적화 (내장 효율 알고리즘)
✅ 프로덕션 모범 사례 (오류 처리, 재시도)
포함된 도구
차량 관리 (4개 도구)
차량 목록, 차량 세부 정보, 실시간 위치, 통계
경로 관리 (6개 도구) ⭐ 당사의 전문 분야
경로 생성, 업데이트, 삭제
정류장 상태 자동 보존 (시간 추적에 중요!)
경로 최적화 (거리/시간 최소화)
경로 목록 및 세부 정보 조회
운전자 관리 (4개 도구)
운전자 목록, 운전자 세부 정보
근무 시간(HOS) 규정 준수 추적
안전 이벤트 모니터링
주소 및 위치 (2개 도구)
저장된 주소 생성 및 관리
지오펜스 통합
웹훅 통합 (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 패키지
@automation-squad/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은 ~나 상대 경로를 인식하지 않습니다.
EU 고객: 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가 수행할 작업:
올바른 주소로 경로 생성
정류장 순서 자동 최적화
추적을 위해 모든 정류장 ID 보존
요청 시 차량/운전자 할당
차량 위치 추적
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 통합 구축 vs. 이 MCP
기능 | 직접 API | 이 MCP |
설정 시간 | 며칠 | 몇 분 |
정류장 상태 보존 | 수동 | 자동 |
속도 제한 | 직접 구현 | 내장 |
오류 처리 | 맞춤 설정 | 프로덕션 테스트 완료 |
경로 최적화 | 직접 구축 | 포함 |
모범 사례 | 연구 필요 | 내장 |
공식 MCP(존재한다면) vs. Automation Squad
기능 | 가상의 공식 MCP | Automation Squad |
도구 수 | 약 8-12개 기본 | 21개 |
API 범위 | 약 10% | 차량, 경로, 운전자, HOS, 웹훅 |
전문 지식 | ❌ | ✅ 내장 |
경로 최적화 | ❌ | ✅ 포함 |
상태 보존 | 수동 | 자동 |
업데이트 | 산발적 | 지속적 |
🛠️ 아키텍처
속도 제한
초당 5회 요청으로 보수적으로 설정되어 있으며, 자동 조절 및 재시도 로직이 포함되어 있습니다.
오류 처리
429(속도 제한) 시 자동 재시도
명확한 오류 메시지
우아한 성능 저하
상태 보존
중요 기능: 경로 업데이트 시 자동으로:
기존 경로 가져오기
정류장 ID 추출
업데이트 시 보존
데이터 손실 방지
이는 도착/출발 시간 손실을 방지하는 모범 사례입니다.
📚 문서
환경 변수
변수 | 필수 | 기본값 | 설명 |
| ✅ 예 | - | Samsara API 토큰 |
| 아니요 |
| API 기본 URL (필요 시 EU 엔드포인트 사용) |
도구 명명 규칙
모든 도구는 명확성을 위해 samsara_ 접두사를 사용합니다:
samsara_list_vehiclessamsara_create_routesamsara_get_driver_hos등
🤝 TMS 통합
경로/차량/운전자에 externalIds를 사용하여 TMS와 연결:
{
"externalIds": {
"tmsOrderId": "ORD-12345",
"customerId": "CUST-789"
}
}그런 다음 외부 ID로 조회:
Find the route linked to TMS order ORD-12345🐛 문제 해결
"오류: SAMSARA_API_TOKEN 환경 변수가 필요합니다"
Claude 설정 파일에 API 토큰을 설정하세요 (위 설정 참조).
"Samsara API 오류 (401): 권한 없음"
API 토큰이 유효하지 않거나 만료되었습니다. Samsara 대시보드에서 새 토큰을 생성하세요.
"Samsara API 오류 (429): 요청이 너무 많습니다"
MCP가 자동으로 재시도합니다. 자주 발생한다면 다른 통합이 API를 사용 중일 수 있습니다.
Claude에 도구가 표시되지 않음
설정 파일 구문 확인 (유효한 JSON)
Claude를 완전히 재시작 (종료 후 다시 열기)
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는 완전히 로컬에서 실행됩니다.
📈 로드맵
추가 도구 (배차, 자산, 태그)
배치 작업 지원
향상된 최적화 알고리즘
다중 경로 최적화
연료 비용 계산
규정 준수 보고 도구
🎓 더 알아보기
💬 지원
베타 사용자:
이메일: rob@matrix.digital
GitHub 이슈: 버그 신고
📝 라이선스
MIT 라이선스 - 자세한 내용은 LICENSE 파일 참조
🙏 크레딧
❤️로 제작: Automation Squad
Samsara Inc.와 제휴 관계 없음. 이는 Samsara의 공개 API를 사용하는 독립적인 통합입니다.
⭐ Automation Squad의 다른 제품
문서, 설치 단계 및 이 서버가 수행하지 않는 작업: automationsquad.com/mcp/samsara
The AI Five — AI와 자동화에 대해 알아야 할 다섯 가지, 주간 발행. 무료 구독 →
차량 관리를 자동화할 준비가 되셨나요? 시작해 봅시다! 🚀
Available Tools
21 toolssamsara_create_addressC
Create a saved address/location in Samsara for reuse in routes
Inputs: name (required), latitude, longitude, externalIds, +1 more.
samsara_create_contactC
Create a contact (person at a stop location) for route management
Inputs: firstName (required), email, phone, lastName, +1 more.
samsara_create_routeA
Create a new route with stops. IMPORTANT: Each stop needs address (with lat/long or formatted address), optional arrival/departure times, and names. Use externalIds to link with your TMS.
Inputs: name (required), stops (required), driverId, startTime, +2 more.
samsara_create_webhookB
Create a webhook to receive real-time notifications from Samsara (route updates, vehicle events, etc.)
Inputs: url (required), eventTypes (required), secret.
samsara_delete_routeC
Delete a route permanently
Inputs: routeId (required).
samsara_delete_webhookC
Delete a webhook subscription
Inputs: webhookId (required).
samsara_get_driverC
Get detailed information about a specific driver
Inputs: driverId (required).
samsara_get_driver_hosC
Get Hours of Service (HOS) logs for a driver. Essential for compliance tracking.
Inputs: endTime (required), driverId (required), startTime (required).
samsara_get_driver_safety_eventsC
Get safety events (harsh braking, acceleration, speeding, etc.) for a driver
Inputs: endTime (required), driverId (required), startTime (required).
samsara_get_routeA
Get detailed information about a specific route including all stops, assigned vehicle/driver, and status
Inputs: routeId (required).
samsara_get_vehicleB
Get detailed information about a specific vehicle by ID
Inputs: vehicleId (required).
samsara_get_vehicle_locationsA
Get real-time or recent locations for vehicles. Uses the feed API pattern for efficient streaming of location data.
Inputs: after, vehicleIds.
samsara_get_vehicle_statsB
Get vehicle statistics including odometer, engine hours, and fuel usage over a time range
Inputs: endTime (required), startTime (required), vehicleIds (required).
samsara_list_addressesB
List all saved addresses
Inputs: after, limit.
samsara_list_contactsD
List all contacts
Inputs: limit.
samsara_list_driversC
List all drivers in the organization with their details and external IDs
Inputs: after, limit.
samsara_list_routesA
List all routes. Routes contain ordered stops with addresses, times, and status tracking.
Inputs: after, limit.
samsara_list_vehiclesA
List all vehicles in the fleet. Returns vehicle details including ID, name, VIN, make, model, and external IDs for TMS integration.
Inputs: after, limit.
samsara_list_webhooksB
List all configured webhooks
Inputs: no named parameters.
samsara_optimize_routeB
Optimize route stop order to minimize distance/time. This is a value-add feature that reorders stops for efficiency while preserving all stop data and IDs.
Inputs: routeId (required), optimizationGoal.
samsara_update_routeA
Update a route. CRITICAL BEST PRACTICE: This tool automatically preserves stop IDs to maintain arrival/departure time tracking. You can update name, vehicle, driver, status, or modify stops. When updating stops, the tool fetches existing stop IDs and preserves them.
Inputs: routeId (required), name, stops, status, +2 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 21 tools
Most tools have distinct purposes (vehicles, routes, drivers, addresses, webhooks, contacts). However, samsara_list_vehicles and samsara_get_vehicle could be confused by an agent as simply different granularities of the same resource, which is acceptable. No major overlapping ambiguity.
All tools follow a consistent samsara_{verb}_{noun} pattern with clear CRUD verbs (list, get, create, update, delete) and one value-add verb (optimize). The naming is predictable and uniform, making it easy for an agent to infer tool purpose.
21 tools covers a fleet management domain (vehicles, routes, drivers, HOS, safety, addresses, webhooks, contacts) reasonably well. It is on the higher side but each tool serves a clear function. Slightly over 15 but not excessive for the scope.
The toolset provides good CRUD coverage for routes, addresses, webhooks, and contacts, plus read-only access for vehicles and drivers with HOS and safety. Missing update/delete for drivers and vehicles, and no update for addresses/contacts, but the core fleet workflows (routing, driver monitoring) are well-covered.
Maintenance
Related MCP Connectors
Tesla Fleet API for AI: send navigation destinations, read battery and location, run car commands.
AI for your car: check charge, start climate, lock/unlock, open trunk via Tesla Fleet API. OAuth.
Read-only access to your Drivara fleet — jobs, drivers, vehicles, fuel, profit & analytics.
CO3 portal data for AI assistants: trackings, assets, ETA, cold chain, driver hours, CO₂.
1
Related MCP Servers
- FlicenseAqualityCmaintenanceEnables AI agents to query orders, manage routes, track drivers, and analyze delivery performance on the FleetSync last-mile delivery platform through natural language.18-
- FlicenseNot gradedqualityCmaintenanceExposes live Samsara fleet data via MCP tools for searching assets and retrieving GPS locations.-
- AlicenseNot gradedqualityCmaintenanceIntegrates with Tesla Fleet API and TeslaMate API to control vehicles, monitor energy (Powerwall/Solar), manage charging, and analyze driving data, with generative UI and skill workflows.5MIT
- AlicenseNot gradedqualityBmaintenanceProvides real-time freight tracking and load visibility for logistics and AI agents: create loads, get live GPS positions, trip stats, and confirm deliveries via geofenced statuses.1MIT