evaconnect

Русский

Typed Python client and stdio MCP server for the Evolute companion API (https://app.evassist.ru). Own account / own vehicle only.

Read telemetry (charge, climate, doors, online) and recent trips without the official Android app. Vehicle commands are not implemented — the command channel is unconfirmed.

Install

Python 3.12+.

cd evaconnect
python3.12 -m venv .venv
source .venv/bin/activate
pip install ".[dev]"

Do not use pip install -e on Python 3.14 / macOS. Hatchling marks the .pth as Finder-hidden; 3.14 then skips it. import evaconnect hits a namespace leftover in site-packages/evaconnect (often only schema.sql), and the CLI dies:

ModuleNotFoundError: No module named 'evaconnect'
ModuleNotFoundError: No module named 'evaconnect.cli'

Install a regular wheel (pip install . or pip install ".[dev]"). If you already used -e, either reinstall without it, or:

chflags nohidden .venv/lib/python*/site-packages/*.pth

Then evolute --help should print the subcommands. Repeating pip install -e puts the hidden flag back. Entry points after install:

• evolute — small CLI (status, trips, vehicles, info)

• evaconnect-mcp — stdio MCP server

• evaconnect-poller — write telemetry/trips to Postgres for Grafana

Remote poller + Postgres next to an existing Grafana: see deploy/README.md (RU). Grafana dashboard JSON: deploy/grafana/dashboards/evolute.json (folder Evolute, uid evaconnect-evolute, timezone Europe/Moscow).

Unofficial reverse-engineered HTTP spec (CC0, not vendor docs): api/README.md (RU).

Related MCP server: Rivian MCP

Auth

There is no password. The official app logs in with an SMS code. evaconnect does the same: one SMS, then a token pair. The CLI has no login command (and MCP never requests OTP). Use a short Python snippet.

1. Get tokens

phone / phoneCountry are whatever the official app sends. The vendor does not document the mask; a live login used an 11-digit number (country code + national number, no +) and a two-letter phoneCountry.

from evaconnect import EvoluteClient

phone = "00000000000"
phone_country = "XX"

with EvoluteClient() as client:
    client.get_info()  # optional; field is capcha, not captcha
    client.request_otp(phone, phone_country)  # sends one SMS

When the SMS arrives:

from evaconnect import EvoluteClient

with EvoluteClient() as client:
    client.sign_in("00000000000", "000000")  # phone, SMS code

That writes ~/.config/evolute/credentials.json (chmod 600):

{
  "accessToken": "<YOUR_TOKEN>",
  "refreshToken": "<YOUR_REFRESH_TOKEN>",
  "userId": "",
  "userToken": "",
  "widgetId": "",
  "carId": null
}

Override the path with EVOLUTE_CREDENTIALS. carId is optional: if empty, the client uses the first vehicle on the account. Set it after evolute vehicles if you have more than one car.

Do not commit this file, the phone number, VIN, IMEI, or coordinates.

2. Use the tokens

Later calls send header access-token: <accessToken>, not Authorization: Bearer. The client loads the file automatically. Env vars EVOLUTE_ACCESS_TOKEN / EVOLUTE_REFRESH_TOKEN / EVOLUTE_CAR_ID fill empty fields only — they do not override tokens already in the file.

evolute vehicles
evolute status
evolute trips -n 5

from evaconnect import EvoluteClient

with EvoluteClient() as client:
    client.refresh()   # optional; also happens automatically on HTTP 401
    print(client.list_vehicles())
    print(client.get_telemetry(car_id=client.default_car_id()))

curl (same headers the Android client sends):

TOKEN=$(python3 -c "import json,pathlib; p=pathlib.Path.home()/'.config/evolute/credentials.json'; print(json.loads(p.read_text())['accessToken'])")
curl -sS 'https://app.evassist.ru/id-service/user' \
  -H "access-token: $TOKEN" \
  -H 'accept: application/json' \
  -H 'x-device: android' \
  -H 'x-app: mobile' \
  -H 'x-app-version: 5.1.22 (740)'

Poller / Grafana: copy that credentials.json onto the server after the last local use (refresh rotates refreshToken). See deploy/README.md (RU).

MCP: point EVOLUTE_CREDENTIALS at the file, or leave tokens out of mcp.json so the default path is used. Do not put live tokens in git.

When a data request returns 401, the client refreshes once, writes the new pair back to the file, and retries. If refresh itself returns 401, the pair is dead — run sign_in again. HTTP details: api/docs/authentication.md (RU).

Library

from evaconnect import EvoluteClient

with EvoluteClient() as client:
    client.refresh()
    me = client.me()
    cars = client.list_vehicles()          # id, plate, model; VIN/IMEI not in repr
    car = client.get_vehicle(cars[0].id)
    tel = client.get_telemetry(car_id=car.id)  # or imei=…
    session = client.get_charge_session()      # may be None
    trips = client.list_trips(car.id, limit=5, offset=0)
    trip = client.get_trip(car.id, trips.rows[0].id, trips.rows[0].segment_start_time)

get_telemetry accepts an IMEI or a mongo car _id (24 hex chars) and resolves IMEI when needed. Those two IDs are not interchangeable.

send_command exists only as a stub and always raises NotImplementedError.

CLI

evolute info          # GET /id-service/info (no token)
evolute status
evolute trips -n 5
evolute vehicles

MCP (Cursor)

stdio server. Tools (read-only):

There is no request_otp and no command-sending tool.

Cursor mcp.json example (~/.cursor/mcp.json or project .cursor/mcp.json):

{
  "mcpServers": {
    "evaconnect": {
      "command": "/Users/nmel/Documents/Projects/evaconnect/.venv/bin/evaconnect-mcp",
      "env": {
        "EVOLUTE_ACCESS_TOKEN": "",
        "EVOLUTE_REFRESH_TOKEN": "",
        "EVOLUTE_CAR_ID": ""
      }
    }
  }
}

If the venv is on PATH, "command": "evaconnect-mcp" is enough.

Default MCP output redacts VIN, IMEI, phone, tokens, and exact coordinates (include_pii off). Do not poll telemetry faster than once per 5 seconds (the client caches within that window).

Tests

Mocks only — tests never call production. GitHub Actions runs pytest and Spectral on api/openapi.yaml.

pytest

Grafana dashboard

Provisioned JSON: deploy/grafana/dashboards/evolute.json. Datasource uid evaconnect-pg. Rows:

Trip addresses and coordinates are not stored. See deploy/README.md (RU).

Spec gaps (explicit parameters, no guessing)

• Phone / phoneCountry format is unknown — pass them as strings.

• Trip sort.by / dir default to live-confirmed DATE / DESC (DURATION / DISTANCE and ASC are also valid).

• distance units (m vs km) are unknown — raw int, no conversion.

• Access-token TTL is unknown — one auto-refresh on HTTP 401, no loop.

• Charge-session body when charging is not fully specified. See api/docs/quirks.md (RU).

• Time-Zone header is unused (not confirmed).

Full endpoint table and x-status markers: api/README.md (RU).

License

MIT for the Python client, MCP server, and poller.

The unofficial API description under api/ is CC0-1.0.