FlowTruxFlowTrux/Docs
Docsmcp

Wialon MCP Server

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

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

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)

  1. In FlowTrux, go to Settings → MCP Servers → Add → Wialon (Hosting / Local).
  2. 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.
  3. Click Connect on the saved server card. You'll be redirected to Wialon's login form.
  4. Sign in with your Wialon credentials and approve the FlowTrux integration on the consent screen.
  5. 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

  1. 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.
  2. In FlowTrux, go to Settings → MCP Servers → Add → Wialon (Hosting / Local).
  3. 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)

ToolDescriptionRequired Params
search_itemsUniversal core/search_items for any item type. Use when the helpers below don't fit.itemsType

Item-type wrappers (4)

ToolDescriptionRequired Params
get_unitsList AVL units with last position + last-message timestamp.(none)
get_usersList Wialon users.(none)
get_resourcesList avl_resource containers (zones, drivers, reports, notifications).(none)
get_accountsList billing accounts.(none)

Unit data (3)

ToolDescriptionRequired Params
get_unit_detailsFull data flags for a single unit - position, sensors, drivers, custom fields.unitId
get_messagesPaged messages (positional / chat / driving / SOS) over a time range.unitId, timeFrom, timeTo
get_eventsPoll for events (geofence in/out, sensor crossings, driver assignments) since a cursor.unitIds

Geofences (3)

ToolDescriptionRequired Params
get_geofencesList zones in a resource.resourceId
upsert_geofenceCreate (id=0) or update an existing zone.resourceId, name, type, points
delete_geofenceRemove a zone by id.resourceId, id

Reports (3)

ToolDescriptionRequired Params
execute_reportRun a report template against a unit / unit group. Result is held in session memory.resourceId, reportTemplateId, objectId, timeFrom, timeTo
get_report_resultPull rows out of an executed report's table.tableIndex
cleanup_reportFree the in-memory result. Always call this after you're done reading rows - Wialon holds the data until session end otherwise.(none)

ACL (2)

ToolDescriptionRequired Params
get_item_aclRead the ACL bitmask granted to a user / user-group on an item.itemId, userId
update_item_aclSet the ACL bitmask. Use flags=0 to revoke all access.itemId, userId, flags

Common patterns

Daily mileage report

get_resources → pick the resource holding your report templates → execute_report with the template id, target unit id, and yesterday's timestamp range → get_report_result for each table you care about → cleanup_report.

"Where are my trucks right now?"

get_units (default flags include the last GPS position) → render or filter on pos.x (lon), pos.y (lat), lmsg (last-message ts).

Geofence breach loop

A scheduled trigger every N minutes → get_events with the unit ids of interest, passing the previous run's since cursor (stored in global context) → branch on event type → notify via Slack / email / etc.

Notes

  • 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. The MCP-pool idle-evicts after 5 minutes; the server's auto-relogin handles in-flight expirations.

Deferred to v2

  • Gurtam Maps - forward / reverse geocoding and routing-by-points live on a separate endpoint (gis_geocode, gis_routing) and need their own auth path. Not in v1.
  • Persistent event listeners - get_events is a one-shot poll. A long-running listener would need a Trigger node, not an Action.
← JiraExternal Servers→