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.

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.