# trucksim-mcp

> An [MCP](https://modelcontextprotocol.io) 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](https://github.com/rachittshah/trucksim-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/rachittshah/trucksim-mcp/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)

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`](./tests/fixtures/funbit_sample.json)); and
`trucksim-mcp selftest` confirms your wiring (and flags implausible readings).

## Quickstart

```bash
# 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`](./docs/clients.md) for Claude Desktop / Cursor / Cline config, and
[`docs/sources.md`](./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`](./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](https://github.com/RenCloud/scs-sdk-plugin)) into the game's `bin/win_x64/plugins/`.
2. Run a telemetry HTTP server ([Funbit/ets2-telemetry-server](https://github.com/Funbit/ets2-telemetry-server), port 25555).
3. Configure and **verify the wiring** before touching an MCP client:

   ```bash
   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
   ```

   ```text
   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`](./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`](./docs/menubar.md).

```bash
# 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:

```text
$ 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`](./agent/README.md).

## Documentation

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

## License

[MIT](./LICENSE) © Rachitt Shah. Not affiliated with or endorsed by SCS Software.
Euro Truck Simulator 2 and American Truck Simulator are trademarks of SCS Software.