Automation Squad - Samsara용 MCP

Claude AI를 위한 완벽한 Samsara 차량 관리 통합
21개 도구 | 내장된 전문 지식 | 베타

🚀 베타 기간 동안 무료 - 평생 할인 혜택을 지금 확보하세요!

⚠️ 중요 고지사항

비공식 통합: 이는 비공식 타사 MCP 서버입니다. 다음 사항을 숙지하세요:

• ❌ Samsara Inc.와 제휴, 보증 또는 후원을 받지 않습니다.

• ❌ 공식 Samsara 제품이 아닙니다.

• ✅ 자체 API 자격 증명을 사용하여 Samsara의 공개 API를 기반으로 구축되었습니다.

• ✅ Samsara의 API 이용 약관을 완전히 준수합니다.

**Samsara®**는 Samsara Inc.의 등록 상표입니다.

Related MCP server: fleetsync-mcp

🎯 기능

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가 수행할 작업:

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 통합 구축 vs. 이 MCP

공식 MCP(존재한다면) vs. Automation Squad

🛠️ 아키텍처

속도 제한

초당 5회 요청으로 보수적으로 설정되어 있으며, 자동 조절 및 재시도 로직이 포함되어 있습니다.

오류 처리

• 429(속도 제한) 시 자동 재시도

• 명확한 오류 메시지

• 우아한 성능 저하

상태 보존

중요 기능: 경로 업데이트 시 자동으로:

1. 기존 경로 가져오기

2. 정류장 ID 추출

3. 업데이트 시 보존

4. 데이터 손실 방지

이는 도착/출발 시간 손실을 방지하는 모범 사례입니다.

📚 문서

환경 변수

도구 명명 규칙

모든 도구는 명확성을 위해 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

🐛 문제 해결

"오류: SAMSARA_API_TOKEN 환경 변수가 필요합니다"

Claude 설정 파일에 API 토큰을 설정하세요 (위 설정 참조).

"Samsara API 오류 (401): 권한 없음"

API 토큰이 유효하지 않거나 만료되었습니다. Samsara 대시보드에서 새 토큰을 생성하세요.

"Samsara API 오류 (429): 요청이 너무 많습니다"

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 웹사이트

💬 지원

베타 사용자:

• Automation Squad 커뮤니티 가입

• 이메일: rob@matrix.digital

• GitHub 이슈: 버그 신고

📝 라이선스

MIT 라이선스 - 자세한 내용은 LICENSE 파일 참조

🙏 크레딧

❤️로 제작: Automation Squad

Samsara Inc.와 제휴 관계 없음. 이는 Samsara의 공개 API를 사용하는 독립적인 통합입니다.

⭐ Automation Squad의 다른 제품

문서, 설치 단계 및 이 서버가 수행하지 않는 작업: automationsquad.com/mcp/samsara

The AI Five — AI와 자동화에 대해 알아야 할 다섯 가지, 주간 발행. 무료 구독 →

차량 관리를 자동화할 준비가 되셨나요? 시작해 봅시다! 🚀