OneMap8 MCP Server

Exposes a OneMap8 fleet tracking installation to Claude, ChatGPT, and any other MCP client, so people can ask questions in plain language instead of driving the report UI:

Where is Truck 12 right now? How many kilometres did the delivery fleet cover last week? Email me the trips report for the vans, Monday to Friday. Which vehicles raised alarms overnight?

32 tools covering the full API surface — devices, positions, all seven report types, geofences, drivers, maintenance, notifications, calendars, users, permissions, and device command dispatch.

Quick start

npm install && npm run build

Copy .env.example to .env and fill in your server URL and a token:

cp .env.example .env

Verify the connection end to end:

npm test

Authentication

The plugin never has more access than the OneMap account behind it. Whatever devices, groups and reports that user can see through the web UI is exactly what the model can reach — OneMap's own permission system does the enforcement, and there is no separate privilege model to keep in sync.

Two options, set in .env:

• ONEMAP_TOKEN (recommended) — an API token minted for the account. Sent as a bearer token. Revocable without changing the password.
• ONEMAP_EMAIL + ONEMAP_PASSWORD — basic auth. Works, but leaves the password in plain text on disk; use it only to get going.

Connecting a client

Claude Desktop / Claude Code (stdio)

Add to claude_desktop_config.json (or .mcp.json for Claude Code):

{
  "mcpServers": {
    "onemap8": {
      "command": "node",
      "args": ["/absolute/path/to/ai-plugin/dist/stdio.js"],
      "env": {
        "ONEMAP_URL": "https://mcp.onemap8.com/api",
        "ONEMAP_TOKEN": "your-token-here",
        "ONEMAP_ALLOW_COMMANDS": "false"
      }
    }
  }
}

Remote / ChatGPT connector (HTTP)

npm run start:http

Serves Streamable HTTP on POST /mcp (health check at /health). It runs stateless — a fresh server per request, nothing shared between callers — so one deployment can serve many users.

With ONEMAP_HTTP_PASSTHROUGH_AUTH=true (the default) each request's Authorization: Bearer <token> header supplies that caller's own OneMap token, so every user is scoped to their own permissions rather than sharing one service account.

Before exposing it publicly:

• Terminate TLS in front of the process — tokens travel in headers.
• Set ONEMAP_ALLOWED_ORIGINS if browser-based clients will connect; unlisted origins are refused.
• This does not implement OAuth. Either front it with a gateway that does, or hand each user a OneMap API token to paste into their client.

Guardrails

The account's own permissions are the real security boundary. These flags are the second layer — they limit what the model can do with that account, which is a different question from what the account is allowed to do.

Variable	Default	Effect
ONEMAP_READONLY	false	Refuses every write. Reports and queries still work.
ONEMAP_ALLOW_COMMANDS	true	Set false to disable device command dispatch entirely.
ONEMAP_ALLOW_DANGEROUS	false	Gates position deletion, user deletion, device deletion, server settings and reboot.
ONEMAP_MAX_ROWS	200	Truncates large result sets before they flood the context window.

Two tools additionally require an explicit confirm: true argument, on top of the flags above: onemap_send_command and onemap_delete_positions.

On device commands specifically: onemap_send_command reaches physical hardware — engine immobilisers, door locks, relays. Enabling it means a language model is one tool call away from stopping a vehicle. It is on by default because you asked for the full surface, but consider ONEMAP_ALLOW_COMMANDS=false for any deployment where users other than you can reach it, and leaving command dispatch to the operators' own UI.

Scheduled reports

The OneMap API has no recurring-schedule endpoint. It can email a report once, on request — onemap_report with delivery: "mail" hits /reports/{type}/mail, and the server emails the spreadsheet asynchronously to the account owner.

Making that repeat is an external scheduler calling the same thing on a cadence:

Approach	Good for	Watch out for
cron / n8n hitting /reports/{type}/mail directly	Production. Reliable, centralised, independent of any AI client, survives the plugin being uninstalled.	A little backend work; lives outside this repo.
Scheduled task in Claude or ChatGPT firing a prompt that calls onemap_report	Personal use, quick experiments, reports where you want the model to summarise before sending.	Depends on the AI platform's task infra — tasks can be paused or lost, and timing is not guaranteed.

For anything a business depends on, use the first. The schedule_recurring_report prompt walks through picking the report and parameters, runs it once so you can check the output, and then lays out both options.

An n8n version is roughly: Schedule Trigger → HTTP Request GET {ONEMAP_URL}/reports/trips/mail with deviceId, from, to and an Authorization: Bearer header.

Tool reference

Fleet state — onemap_list_devices, onemap_get_device, onemap_list_groups, onemap_live_positions, onemap_position_history, onemap_get_event, onemap_geocode, onemap_whoami, onemap_statistics, onemap_audit_log

Reports — onemap_report (route, events, trips, stops, summary, geofences, combined × json/xlsx/mail), onemap_report_devices_xlsx

Configuration — onemap_geofences, onemap_drivers, onemap_maintenance, onemap_calendars, onemap_notifications, onemap_computed_attributes, onemap_orders (each takes an action: list/get/create/update/delete)

Commands — onemap_command_types, onemap_saved_commands, onemap_send_command

Administration — onemap_manage_device, onemap_manage_group, onemap_users, onemap_permissions, onemap_share, onemap_send_notification, onemap_session_token, onemap_stream_url, onemap_server_settings, onemap_delete_positions

Design notes

Two decisions worth knowing about when extending this:

• Names resolve to ids server-side. Tools accept deviceNames: ["Truck 12"] and look the id up, because users say names and models guess ids. Ambiguous names are rejected with the candidates listed rather than resolved to a guess — picking the wrong vehicle silently is worse than failing.
• One report tool, not eight. The seven report endpoints differ only by path segment, so they are one tool with a report discriminator. Short tool lists measurably improve model selection accuracy; the same reasoning collapses entity CRUD into one action-dispatched tool each.

Named periods (period: "lastWeek") are resolved server-side too — weeks start Monday — because date arithmetic is a reliable source of quiet model errors.

Two API quirks worth knowing before you touch these code paths, both found by testing against the live server rather than by reading the spec:

• GET /session ignores Authorization: Bearer. It reports on the cookie session and answers 404 when there is none. Token clients must pass ?token=, which OneMapClient.getSessionUser() does as a fallback only — that puts the credential in the server's access log, so it is never the first attempt.
• id on /positions means position id, not device id, and deviceId requires an explicit from/to. "Latest position" is therefore GET /positions with no parameters, filtered client-side. Passing a device id as id gets a 500 (NullPointerException) from the server.

Development

npm run dev        # tsc --watch
npm test           # build + smoke tests against a mock API
npm run inspect    # MCP Inspector against the stdio server

test/smoke.mjs stands up a fake OneMap API and drives the real server through an in-memory MCP client, covering name resolution, period expansion, array query encoding, mail delivery, and every guardrail.