Skip to main content
Glama
trucksim-mcp

trucksim-mcp

by rachittshah

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.

CI License: MIT Python 3.10+

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

Related MCP server: msfs2024-mcp

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.

Available Tools

10 tools
check_speedingA
Read-onlyIdempotent

Are you speeding right now, and by how much over the posted limit?

Inputs: no named parameters. Returns: result

get_active_jobA
Read-onlyIdempotent

The current delivery job: cargo, route, pay, deadline, and on-time status.

Inputs: no named parameters. Returns: result

get_eco_scoreA
Read-onlyIdempotent

A 0-100 driving score for this session, with the factors dragging it down.

Inputs: no named parameters. Returns: result

get_fuel_statusA
Read-onlyIdempotent

Fuel level, consumption, estimated range, and whether it's enough to reach the routed destination.

Inputs: no named parameters. Returns: result

get_navigationA
Read-onlyIdempotent

Routing status: distance and ETA to the destination, posted limit, and whether you're currently speeding.

Inputs: no named parameters. Returns: result

get_raw_telemetryA
Read-onlyIdempotent

The full normalized telemetry snapshot as JSON (for power users / debugging).

Inputs: no named parameters. Returns: result

get_rest_advisorA
Read-onlyIdempotent

Fatigue guidance based on continuous driving time (EU hours-of-service style).

Inputs: no named parameters. Returns: result

get_trip_summaryA
Read-onlyIdempotent

Rolling trip totals since the server started: distance, time, speeds, fuel, events.

Inputs: no named parameters. Returns: result

get_truck_stateA
Read-onlyIdempotent

Current truck state: speed vs limit, engine, gear, cruise, fuel, damage, lights.

The one-call "what's happening right now" snapshot. Works with any configured source (mock/http/mmap).

Inputs: no named parameters. Returns: result

list_recent_eventsA
Read-onlyIdempotent

Recent driving events (speeding, hard braking, collisions, refuels), newest first.

Inputs: limit. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 10 tools

    Disambiguation4/5

    Each tool targets a distinct aspect of the truck state (speed, fuel, navigation, job, etc.), but there is some overlap: get_truck_state includes speed/fuel while check_speeding and get_fuel_status focus on those specifically. Descriptions clarify the focus, so agents can generally select correctly.

    Naming Consistency3/5

    Most tools follow a get_ verb pattern, but check_speeding and list_recent_events break the convention with different verbs. This is more than a minor deviation, though still readable and predictable overall.

    Tool Count5/5

    With 10 tools, the server is well-scoped for a truck telemetry/monitoring purpose. Each tool has a clear role, and none feel redundant or missing at this granularity.

    Completeness4/5

    The tool set covers a broad range of truck and driver status (state, navigation, fuel, job, speeding, eco, trip, rest, events, raw data). Missing operations like historical queries or filtered events are minor gaps that most workflows can work around.

    Maintenance

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    • AI race engineer for sim racing (Automobilista 2, Assetto Corsa, Assetto Corsa Competizione, Assetto Corsa Evo, RaceRoom). Provides telemetry analysis, braking diagnostics, and leaderboards. Connected via public demo by default. Get your free personal token at [https://flowix.com](https://flowix.com) to analyze your own laps.

      https://flowix.com/mcp/demo
    • tri-train is a training platform for triathletes that syncs activities from Strava and Garmin and exposes them to Claude through a remote MCP server. Ask Claude how your last block went, why your run pace dropped, or whether you are fresh enough for Sunday's race, and it answers from your real data: activities with laps and grade-adjusted pace, weekly load and the performance management chart (CTL/ATL/TSB), sleep, HRV and resting heart rate, and your race calendar with predictions. Claude can also act: create and adjust planned workouts with structured intervals, push them to your Garmin watch, add races and write notes. Every change is journaled and can be undone. Read and write access are separate OAuth scopes, and the server enforces them on every call. Built and hosted in Switzerland by a triathlete; data stays on our own servers (Swiss revDSG / GDPR).

      https://tri-train.com/api/mcp
    • Furgonetka MCP Server is an extension for LLMs (such as Claude) that integrates AI assistants with Poland's most popular courier brokerage platform. The server enables models to interact directly with services from various couriers (including InPost, DPD, DHL, UPS, and Poczta Polska) through a single, unified interface. With this integration, your AI stops just "writing about logistics" and starts actually managing it.

      https://api.furgonetka.pl/mcp
    • Remote streamable-HTTP MCP server running on a single Cloudflare Worker. Your assistant gets live Airbnb, Amazon, Booking.com, Google Flights, Maps and Reddit data, social search on X, Instagram and TikTok, the Meta Ad Library, and image/video generation without any keys. Connect your own accounts to let it send WhatsApp or Telegram messages, work an IMAP inbox, manage Meta Ads campaigns and publish to X and LinkedIn. OAuth 2.1 with PKCE; stored credentials are AES-256-GCM encrypted.

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      A local MCP server that gives Claude (or any MCP-compatible AI client) access to Formula 1 race data. Load any session from 2018 onwards, ask questions in natural language, and get answers backed by real telemetry, timing, and strategy data.
      17
      1
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Enables MCP clients like Claude to read live state and control aircraft in Microsoft Flight Simulator 2024 via SimConnect, FSUIPC7, and raw memory, offering 23 tools for simvars, events, autopilot, and more.
      23
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Local MCP server that connects Claude Desktop with Garmin and Apple Health data to read training and recovery, estimate heart rate and pace zones, analyze performance, and create structured workouts.
      22
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      MCP server that provides Forza Horizon 5 telemetry tools (session listing, summaries, telemetry windows, tuning recommendations) to AI assistants, enabling natural language queries about driving sessions.
      -