Witzense MCP

MCP server for the Witzense/JIMI device tracking Open API described in API DOCUMENT.pdf.

The extracted Markdown reference is API DOCUMENT.md. It preserves all 126 PDF pages as page sections and is easier to search and process programmatically. The PDF remains the original source, and image-only content is not embedded in the Markdown extraction.

Configuration

Copy .env.example to a local environment configuration and set:

• WITZENSE_BASE_URL: defaults to http://open.10000track.com/route/rest.
• WITZENSE_APP_KEY and WITZENSE_APP_SECRET.
• WITZENSE_ACCOUNT and WITZENSE_PASSWORD_MD5 — the account password's existing 32-character lowercase MD5; do not provide plaintext and do not hash this value again.
• WITZENSE_EXPIRES_IN: token lifetime request, from 60 to 7200 seconds.
• WITZENSE_REQUEST_ENCODING: form by default, or json if the assigned node requires it.

Never commit real credentials or place them in source files.

Run

npm install
npm run build
npm start

The server communicates over MCP stdio. Available tools include:

• call_witzense_method
• list_witzense_child_accounts
• list_witzense_devices
• get_witzense_device
• get_witzense_device_locations
• list_witzense_account_locations
• get_witzense_track
• get_witzense_mileage
• get_witzense_shared_location_url
• list_witzense_alarms
• get_witzense_parking_report
• get_witzense_trips_report
• get_witzense_fence_duration_report
• get_witzense_obd_data
• get_witzense_obd_faults
• get_witzense_rfid_reports
• get_witzense_tag_location
• list_witzense_geofences
• get_witzense_geofence
• list_witzense_device_groups
• get_witzense_media_urls
• get_witzense_live_url
• get_witzense_rtmp_url

The dedicated tools are read-oriented and use the shared signed client.

For Command Cloud integrations, each Witzense device/IMEI is treated as the corresponding Command Cloud asset/vehicle. See specs/commandcloud-mapping.md.

API behavior

Requests use POST /route/rest with common parameters, an access token, and an uppercase UTF-8 MD5 signature. Tokens are acquired through jimi.oauth.token.get, refreshed through jimi.oauth.token.refresh, and cached in memory.

The PDF lists TS, TSP HK, TSP EU, and TSP US nodes. Configure the assigned node through WITZENSE_BASE_URL; do not change tool code when moving between nodes.

Tests

npm test

Server deployment

The repository workflow builds and tests pull requests, then deploys /root/WITZENSE-MCP after a push to main. Configure the GitHub Actions secret DEPLOY_SSH_KEY with the deployment key accepted by root@2.25.109.42.

Keep the Witzense API variables in the server's runtime environment or MCP host configuration. They are intentionally not part of the deployment workflow or repository.

See DEPLOYMENT.md for first-server bootstrap and smoke-test commands.