trucksim-mcp

MCP 서버로 Euro Truck Simulator 2와 American Truck Simulator 텔레메트리 — 실시간 주행 분석 포함 —를 모든 AI 도구(Claude Desktop, Claude Code, Cursor, Cline, …)로 스트리밍합니다. 차량 내 디스패처/운전 코치 역할을 하는 헤드리스 Claude 분석 에이전트도 포함됩니다.

어시스턴트에게 "과속 중인가요?", "배송 마감을 지킬 수 있을까요?", "연료로 얼마나 더 갈 수 있나요?", *"지금까지 운전 점수를 매겨 줘"*라고 물어보세요 — 실시간 게임 텔레메트리로 답을 얻을 수 있습니다. 이 서버는 읽기 전용, 텔레메트리 및 분석 서버입니다: 트럭을 절대 제어하지 않습니다.

참고: "American Truck Simulator 2"는 별도 게임이 아닙니다 — SCS는 여전히 원래 ATS를 출시합니다. ATS와 ETS2는 같은 엔진과 텔레메트리 SDK를 공유하므로 trucksim-mcp는 별도 설정 없이 둘 다 지원합니다.

작동 방식

ETS2 / ATS ──(SCS Telemetry SDK)──▶ telemetry source ──▶ trucksim-mcp ──▶ any MCP client
                                     (mmap | http | mock)   (tools+analytics)   (Claude, Cursor…)

SCS SDK가 Windows 공유 메모리에 쓰기 때문에 trucksim-mcp는 플러그형 소스를 통해 텔레메트리를 읽습니다:

mock 소스 덕분에 게임이 설치되지 않은 상태에서도 전체 파이프라인을 어떤 OS에서든 종단 간 실행할 수 있습니다.

빠른 시작

# no install, straight from GitHub (PyPI release pending)
TRUCKSIM_SOURCE=mock uvx --from git+https://github.com/rachittshah/trucksim-mcp trucksim-mcp

Claude Desktop / Cursor / Cline 설정은 docs/clients.md에서, 실제 ETS2/ATS 텔레메트리 연동 방법은 docs/sources.md에서 확인하세요.

로컬 ETS2 / ATS 연결

mock 소스는 게임이 필요 없지만, 실제 게임을 읽으려면 소스를 선택하세요(docs/sources.md에 전체 가이드가 있습니다):

크로스 플랫폼 (권장) — 게임은 Windows에서 실행되고, trucksim-mcp는 LAN 어디서든 실행할 수 있습니다:

1. SCS 텔레메트리 플러그인(RenCloud/scs-sdk-plugin)을 게임의 bin/win_x64/plugins/에 설치합니다.

2. 텔레메트리 HTTP 서버(Funbit/ets2-telemetry-server, 포트 25555)를 실행합니다.

3. MCP 클라이언트를 다루기 전에 구성을 설정하고 연결 상태를 검증합니다:

   export TRUCKSIM_SOURCE=http
   export TRUCKSIM_HTTP_URL=http://<game-pc-ip>:25555/api/ets2/telemetry
   uvx --from git+https://github.com/rachittshah/trucksim-mcp trucksim-mcp selftest

   source: http
   connected: True
   game:   ets2
   speed:  84 km/h (limit 90)
   job:    Reefer  Frankfurt -> Munich
   ✅ Telemetry is live. Point your MCP client at this same config.

네이티브 Windows — 게임과 같은 PC에서 trucksim-mcp를 실행합니다: TRUCKSIM_SOURCE=mmap(실험적)을 설정하고 trucksim-mcp selftest를 실행하세요.

그런 다음 동일한 환경 변수(env)를 MCP 클라이언트 설정 또는 agent/mcp.json에서 사용하세요.

도구

읽기 전용 도구 10개 — 전체 참조는 docs/tools.md:

• 상태 — get_truck_state, get_navigation, get_fuel_status, get_raw_telemetry

• 작업 — get_active_job

• 분석 — check_speeding, get_eco_score, get_trip_summary, get_rest_advisor, list_recent_events

예시 프롬프트

연결이 완료되면(TRUCKSIM_SOURCE=mock)이lso 포함하여) 어시스턴트에게 물어보세요:

• "내 트럭이 지금 뭘 하고 있나요?" → get_truck_state

• "과속 중인가요?" → check_speeding

• "목적지까지 갈 연료가 충분한가요?" → get_fuel_status

• "배송 마감을 지킬 수 있을까요?" → get_active_job

• "내 운전을 평가하고 무엇을 고쳐야 할지 알려줘." → get_eco_score & get_trip_summary

• "쉬어야 할까요?" → get_rest_advisor

실제 동작하는 코칭 에이전트

내장된 mock 운행에 헤드리스 에이전트를 연결해 실행한 결과입니다 — 실제 claude -p(Sonnet 5)가 이 서버를 통해 텔레메트리를 읽는 모습:

$ TRUCKSIM_AGENT_ONCE=1 ./agent/coach.sh

Heads up: your Hamburg steel-tubes job is projected LATE — ETA 7h7m vs a 4h59m
deadline, a 2h7m shortfall, so this delivery needs a route/time fix, not just
steady driving. Speed and fuel are fine: you're well under the 90 km/h limit,
damage is only 3%, and fuel (688L, ~2149 km range) easily covers the 285 km
trip. Recommendation: check for a faster route or accept the late penalty now.

헤드리스 분석 에이전트

agent/에는 이 MCP 서버에 연결해 실시간 텔레메트리에서 주기적으로 차량 내 코칭 업데이트를 만들어 내는 Claude Code 헤드리스(claude -p, Sonnet 5) 백그라운드 러너가 포함되어 있습니다 — 목소리 없는 디스패처이지요. agent/README.md를 참고하세요.

라이선스

MIT © Rachitt Shah. SCS Software과 제휴 관계가 아니며, SCS Software의 승인을 받지 않았습니다. Euro Truck Simulator 2와 American Truck Simulator는 SCS Software의 상표입니다.