Cartrack MCP

A small, portable MCP server that exposes a read-only view of a Cartrack fleet through any MCP client that can launch a stdio process.

The server exposes only:

• list_vehicles — an allowlisted vehicle inventory.

• get_vehicle_status — last-known status and location for one exact registration.

It does not expose vehicle commands, account changes, geofence changes, driver edits, or raw upstream responses.

Requirements

• Python 3.10 or newer

• Cartrack Fleet API credentials with read access

• An MCP client that supports stdio servers

The server uses HTTPS-only requests, sends HTTP Basic Authentication only in the Authorization header, enforces exact normalized registration matching, and calculates telemetry freshness from the provider timestamp.

Related MCP server: Victron VRM MCP Server

Installation

Create an isolated environment and install the project:

python3 -m venv .venv
. .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install .

For development and tests:

python -m pip install -e .
python -m pip install pytest

Configuration with environment variables

Set all three variables in the environment used to launch the server:

export CARTRACK_BASE_URL='https://fleetapi.example.com'
export CARTRACK_API_USERNAME='your-api-username'
export CARTRACK_API_PASSWORD='your-api-password'
cartrack-mcp

The base URL must be a complete HTTPS URL. Credentials are never printed or included in request URLs.

Configuration with a credentials file

Create a file outside the repository, for example ~/.config/cartrack/credentials.env:

CARTRACK_BASE_URL=https://fleetapi.example.com
CARTRACK_API_USERNAME=your-api-username
CARTRACK_API_PASSWORD=your-api-password

Point to a different file when needed:

export CARTRACK_CREDENTIALS_FILE=/path/to/credentials.env
cartrack-mcp

The default lookup is user-relative and XDG-compatible: $XDG_CONFIG_HOME/cartrack/credentials.env, or ~/.config/cartrack/credentials.env. Environment variables take precedence over values from the file. Keep the file readable only by the account running the server (for example, mode 600 on Unix); the application does not claim to enforce file permissions.

A missing file, malformed line, missing value, or non-HTTPS URL produces an actionable configuration error on startup.

.env.example contains placeholders only and is safe to copy as a starting template. Do not commit a populated copy.

MCP client configuration

The exact configuration format varies by client. A generic stdio configuration uses the installed console command:

{
  "mcpServers": {
    "cartrack": {
      "command": "cartrack-mcp",
      "args": [],
      "env": {
        "CARTRACK_BASE_URL": "https://fleetapi.example.com",
        "CARTRACK_API_USERNAME": "your-api-username",
        "CARTRACK_API_PASSWORD": "your-api-password"
      }
    }
  }
}

Prefer the client’s secret-management facility instead of storing passwords in a shared configuration file.

Optional: Hermes integration

Hermes can launch the same installed stdio command as one MCP server option. Hermes is not required at runtime and is not a project dependency. Configure it using the normal Hermes MCP configuration for a command named cartrack-mcp, with credentials supplied through its environment mechanism.

Tools

list_vehicles

Input: none.

Returns safe fields such as registration, manufacturer, model, model year, colour, vehicle name, vehicle ID, and timezone. Chassis numbers, tracker serials, credentials, and unrelated provider fields are excluded.

Example shape:

[
  {
    "registration": "TEST123",
    "manufacturer": "Example Motors",
    "model": "Example Model",
    "model_year": 2024,
    "timezone": "Africa/Johannesburg"
  }
]

get_vehicle_status

Input:

{"registration": "TEST 123"}

Spaces and hyphens are normalized for lookup, but the server independently requires one exact normalized match. The result contains last-known event time, telemetry age in minutes, speed, ignition, idling, odometer, bearing, road speed limit, and an allowlisted location object.

Example shape:

{
  "registration": "TEST123",
  "event_ts": "2025-01-01 12:39:42+02",
  "telemetry_age_minutes": 9.0,
  "speed_kmh": 0,
  "ignition": false,
  "location": {
    "latitude": -23.9,
    "longitude": 29.45,
    "position_description": "Example location"
  }
}

Development and tests

From the repository root:

python -m unittest discover -v
python -m compileall -q src tests

After installing development dependencies, pytest can also be used:

pytest -q

Tests use synthetic fixtures and injected transports. They do not contact the Cartrack API.

Troubleshooting

• cartrack-mcp: command not found — activate the virtual environment or use its absolute executable path; reinstall with python -m pip install ..

• Missing configuration — set all three CARTRACK_* variables, or set CARTRACK_CREDENTIALS_FILE to an existing file containing all required keys.

• Malformed credentials file — use one KEY=VALUE entry per line; blank lines and comments are allowed.

• HTTPS error — use the documented Cartrack API HTTPS base URL, not an HTTP URL.

• No exact vehicle match — check the registration; partial and ambiguous matches are intentionally rejected.

• Stale telemetry — telemetry_age_minutes reflects the age of the provider’s last event, not a live position guarantee.

• MCP client cannot start the server — confirm the command is available to the client process, configuration uses stdio, and credentials are supplied in that client’s environment.