Wialon MCP Server

Connect FlowTrux workflows to the Wialon (Hosting / Local) telematics platform - units, messages, geofences, reports, drivers, ACL

The Wialon MCP server exposes 19 tools that talk to the Wialon SDK ajax API, covering the core fleet-management surface: units, messages, events, geofences, reports, drivers, and ACL.

The template gallery also ships 20 ready-made fleet workflows built on this server - geofence breach alerts, daily mileage reports, fuel theft detection, weekly client PDF reports, and more. They're a good starting point before building from scratch.

Setup

There are two ways to provide credentials. The Connect button is the recommended path - fewer steps, no copy-paste - but pasting a token manually still works.

Option A - "Connect Wialon Account" (recommended)

In FlowTrux, go to Settings → MCP Servers → Add → Wialon (Hosting / Local).
Fill in just the Host URL - https://hst-api.wialon.com for Wialon Hosting, https://hst-api.wialon.eu for the EU region, or your site URL for Wialon Local. Leave the API Token field empty. Save.
Click Connect on the saved server card. You'll be redirected to Wialon's login form.
Sign in with your Wialon credentials and approve the FlowTrux integration on the consent screen.
Wialon redirects you back. The token is stored encrypted in the config; the badge flips to Connected with the user name.

If the token is ever revoked or expires, click Reconnect.

Option B - paste a token manually

Get a long-lived API token from Wialon by visiting https://hosting.wialon.com/login.html?client_id=YourApp&access_type=-1&duration=0&flags=4&response_type=token in a browser. After sign-in Wialon includes the token in the redirect URL.
In FlowTrux, go to Settings → MCP Servers → Add → Wialon (Hosting / Local).
Fill in Host URL and paste the token into API Token. Save.

How auth works at runtime

The MCP server exchanges the configured token for a session id (SSID) on first use via svc=token/login. Wialon SSIDs idle-expire after ~5 minutes - the server transparently re-logs in and retries on error 1 / 8, so you don't need to reconnect manually as long as the token itself is still valid.

Tools

Discovery (1)

Tool	Description	Required Params
`search_items`	Universal `core/search_items` for any item type. Use when the helpers below don't fit.	`itemsType`

Item-type wrappers (4)

Tool	Description	Required Params
`get_units`	List AVL units with last position + last-message timestamp.	(none)
`get_users`	List Wialon users.	(none)
`get_resources`	List `avl_resource` containers (zones, drivers, reports, notifications).	(none)
`get_accounts`	List billing accounts.	(none)

Unit data (3)

Tool	Description	Required Params
`get_unit_details`	Full data flags for a single unit - position, sensors, drivers, custom fields.	`unitId`
`get_messages`	Paged messages (positional / chat / driving / SOS) over a time range.	`unitId`, `timeFrom`, `timeTo`
`get_events`	Poll for events (geofence in/out, sensor crossings, driver assignments) since a cursor.	`unitIds`

Drivers (1)

Tool	Description	Required Params
`get_drivers`	List drivers configured in Wialon resources: name, phone, code, and the unit each driver is currently bound to (`currentUnitId` is 0 when unbound). Optional `resourceId` limits to one resource; `nameMask` glob-filters by name.	(none)

Geofences (3)

Tool	Description	Required Params
`get_geofences`	List zones in a resource.	`resourceId`
`upsert_geofence`	Create (id=0) or update an existing zone.	`resourceId`, `name`, `type`, `points`
`delete_geofence`	Remove a zone by id.	`resourceId`, `id`

Reports (5)

`run_report` - one-shot ad-hoc reports (recommended)

run_report builds a report on the fly from a simple spec, executes it, fetches all rows, and cleans up - one call, no pre-created report template needed in Wialon. This is the go-to tool for trips, mileage, fuel, speeding, and geofence data.

Parameter	Required	Description
`objectId`	Yes	Unit id (or unit-group id when `objectType` is `unit_group`)
`objectType`	No	`unit` (default) or `unit_group`
`timeFrom` / `timeTo`	Yes	Report interval, Unix timestamps in seconds
`tables`	Yes	1-3 tables per call, each `{ tableType, columns?, label? }`
`resourceId`	No	Resource to execute under. Omit to auto-use the first resource visible to the token
`maxRowsPerTable`	No	Row cap per table (default 1000, max 5000). `truncated: true` is set when rows were cut off

Available table types (12):

`tableType`	Data
`unit_trips`	Trips: begin/end time + address, duration, mileage, speeds, driver, fuel
`unit_stops`	Short stops (engine on): time, duration, location, driver
`unit_stays`	Parkings (long stays): time, duration, location, driver
`unit_engine_hours`	Engine hours intervals: time, duration, mileage
`unit_speedings`	Speed-limit violations: when, where, max speed vs limit, driver
`unit_geofences`	Geofence visits: zone name, in/out times, time inside
`unit_events`	Registered events: time, event text, location
`unit_fuellings`	Fuel fillings: when, where, volume filled, level before/after
`unit_thefts`	Fuel thefts/drains: when, where, stolen volume, level before/after
`unit_ecodriving`	Eco-driving violations: type, time, penalty points, driver
`unit_digital_sensors`	Digital sensor on-intervals: sensor, on/off time, duration (single unit only - not available for unit groups)
`unit_generic`	Summary statistics (name/value pairs): total mileage, speeds, move/stay time, fuel

Omit columns for sensible defaults per table type; an invalid column id errors with the list of valid ones, so agents self-correct.

Output: { tables: [{ name, label, headers, rowCount, truncated, rows }] } where rows is a string matrix. The execution panel renders this output as a table automatically, and the same matrix plugs directly into pdf:generate_pdf_table (rows) or google-workspace:sheets_append (values) - no reshaping step needed.

Note: Wialon executes one report at a time per user - concurrent run_report calls are serialized automatically.

Pre-built template path

If your Wialon account already maintains custom report templates, run those instead:

Tool	Description	Required Params
`list_report_templates`	List pre-created report templates across your resources - id, name, content type, and the tables each template contains.	(none)
`execute_report`	Run a report template against a unit / unit group. Result is held in session memory.	`resourceId`, `reportTemplateId`, `objectId`, `timeFrom`, `timeTo`
`get_report_result`	Pull rows out of an executed report's table.	`tableIndex`
`cleanup_report`	Free the in-memory result. Always call this after you're done reading rows - Wialon holds the data until session end otherwise.	(none)

ACL (2)

Tool	Description	Required Params
`get_item_acl`	Read the ACL bitmask granted to a user / user-group on an item.	`itemId`, `userId`
`update_item_acl`	Set the ACL bitmask. Use `flags=0` to revoke all access.	`itemId`, `userId`, `flags`

Flags bitmasks. Wialon returns the fields you ask for via a flags integer. The wrappers default to sensible values (get_units = 4097 = base + position + lmsg). Override flags to cut payload size or pull more subsystems.
Pagination. get_messages walks messages/get_messages for you up to maxRows (default 1000). For larger ranges either raise the cap or split the time interval.
Session lifetime. Sessions idle-expire after ~5 minutes; the server's auto-relogin handles in-flight expirations transparently.

← Jira External Servers→