trucksim-mcp

An MCP server that streams Euro Truck Simulator 2 and American Truck Simulator telemetry — plus live driving analytics — to any AI harness (Claude Desktop, Claude Code, Cursor, Cline, …). Includes a headless Claude analytics agent that acts as an in-cab dispatcher/driving coach.

Ask your assistant "Am I speeding?", "Will I make the delivery deadline?", "How's my fuel range?", or "Score my driving so far" — and it answers from live game telemetry. This is a read-only, telemetry-and-analytics server: it never controls the truck.

Note: "American Truck Simulator 2" isn't a separate game — SCS still ships the original ATS. Both ATS and ETS2 share the same engine and telemetry SDK, so trucksim-mcp supports both with no configuration.

How it works

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

Because the SCS SDK writes to Windows shared memory, trucksim-mcp reads telemetry through a pluggable source:

Source	Use it when	Needs the game?
mock	Demos, CI, development — a built-in scripted trip	No
http	The game runs on a Windows PC exposing a JSON telemetry feed (Funbit / trucksim-gps); read it from anywhere	Yes (remote)
mmap	trucksim-mcp runs on the same Windows PC as the game	Yes (local)
replay	Replay a real drive you captured with trucksim-mcp record	No

The mock source means the entire pipeline runs end-to-end on any OS with no game installed; the http mapping is verified against a real captured payload (tests/fixtures/funbit_sample.json); and trucksim-mcp selftest confirms your wiring (and flags implausible readings).

Quickstart

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

See docs/clients.md for Claude Desktop / Cursor / Cline config, and docs/sources.md for wiring up real ETS2/ATS telemetry.

Connect your local ETS2 / ATS

The mock source needs no game; to read your real game, pick a source (docs/sources.md has the full guide):

Cross-platform (recommended) — the game runs on Windows, trucksim-mcp can run anywhere on your LAN:

1. Install an SCS telemetry plugin (RenCloud/scs-sdk-plugin) into the game's bin/win_x64/plugins/.

2. Run a telemetry HTTP server (Funbit/ets2-telemetry-server, port 25555).

3. Configure and verify the wiring before touching an MCP client:

   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.
   

Native Windows — trucksim-mcp on the same PC as the game: set TRUCKSIM_SOURCE=mmap (experimental) and run trucksim-mcp selftest.

Then use the same env in your MCP client config or in agent/mcp.json.

Tools

10 read-only tools — full reference in docs/tools.md:

• State — get_truck_state, get_navigation, get_fuel_status, get_raw_telemetry
• Job — get_active_job
• Analytics — check_speeding, get_eco_score, get_trip_summary, get_rest_advisor, list_recent_events

Example prompts

Once connected (even with TRUCKSIM_SOURCE=mock), ask your assistant:

• "What's my truck doing right now?" → get_truck_state
• "Am I speeding?" → check_speeding
• "Do I have enough fuel to reach the destination?" → get_fuel_status
• "Will I make the delivery deadline?" → get_active_job
• "Score my driving and tell me what to fix." → get_eco_score + get_trip_summary
• "Should I take a break?" → get_rest_advisor

Menu bar apps (talk to Claude in-game)

Two macOS menu bar apps give you a live telemetry glance plus a floating Claude chat overlay that appears over ETS2/ATS — ask about your drive without leaving the game. Full guide: docs/menubar.md.

# Python (all-Python, pip install)
pip install "trucksim-mcp[menubar]" && TRUCKSIM_SOURCE=mock trucksim-mcp menubar

# Native SwiftUI (smoothest full-screen overlay) — see macos/TruckSimMenuBar/

Both float a non-activating NSPanel (fullScreenAuxiliary) over the game, so the chat sits on top without stealing focus.

The coaching agent in action

Running the headless agent against the built-in mock trip — a real claude -p (Sonnet 5) reading telemetry through this server:

$ 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.

The headless analytics agent

agent/ contains a background Claude Code headless (claude -p, Sonnet 5) runner that connects to this MCP server and produces periodic in-cab coaching updates from live telemetry — a dispatcher without the voice. See agent/README.md.

Documentation

Guide	What's in it
docs/tools.md	Generated reference for all 10 MCP tools.
docs/clients.md	Add the server to Claude Desktop / Claude Code / Cursor / Cline / Windsurf.
docs/sources.md	Wire up real telemetry (mock / http / mmap) + tuning.
docs/menubar.md	The two macOS menu bar apps and the in-game chat overlay.
agent/README.md	The headless claude -p coaching agent.
macos/TruckSimMenuBar/README.md	Building the native SwiftUI app.
evals/README.md	The automated, graded evaluation harness.
CONTRIBUTING.md · CHANGELOG.md · RELEASING.md	Contributing, release notes, and the PyPI release process.

License

MIT © Rachitt Shah. Not affiliated with or endorsed by SCS Software. Euro Truck Simulator 2 and American Truck Simulator are trademarks of SCS Software.