teltonika-rms-mcp

An unofficial, community-built Model Context Protocol (MCP) server that lets AI agents (Claude Desktop, Claude Code, or any MCP-compatible client) query and operate a fleet of Teltonika devices through the RMS (Remote Management System) API.

Why

RMS already has a well-documented REST API. MCP is the missing glue that lets an agent use it in plain language:

• "Which devices in company X were offline today, and what was their signal?"

• "Give me a firmware summary of the fleet and list the devices that aren't on the latest version."

• "How much mobile data did Pump-02 use last month on each SIM?"

• "Reboot Gateway-A." (the agent shows you the device and asks before doing it)

Related MCP server: central-mcp-server

Tools

Read tools are annotated readOnlyHint, and reboot_device is annotated destructiveHint, so MCP clients can ask for approval before running it.

Read-only mode: set RMS_READ_ONLY=true and reboot_device is not registered at all.

Quick start

1. Create an RMS API token

In RMS, go to Account settings → Security and enable two-factor authentication, which RMS requires before you can create tokens. Then go to API → Access tokens → Add new access token.

Grant only the scopes you need:

The token is shown only once, so store it safely. Exact scope names can vary between RMS releases; pick them from the list in the RMS UI. If a tool returns HTTP 403, the token is missing the scope for that call.

2. Install

git clone https://github.com/marceloiamunoz/Teltonika_RMS_MCP4IA_example.git
cd Teltonika_RMS_MCP4IA_example
pip install -e .        # or: uv pip install -e .

Requires Python 3.10+.

3. Connect it to Claude Desktop

Add this to claude_desktop_config.json (see examples/claude_desktop_config.json):

{
  "mcpServers": {
    "teltonika-rms": {
      "command": "teltonika-rms-mcp",
      "env": {
        "RMS_API_TOKEN": "paste-your-token-here",
        "RMS_READ_ONLY": "true"
      }
    }
  }
}

Restart Claude Desktop and ask: "Give me a summary of my RMS fleet."

Using Claude Code:

claude mcp add teltonika-rms --env RMS_API_TOKEN=xxx --env RMS_READ_ONLY=true -- teltonika-rms-mcp

Configuration

How it works

AI agent ──MCP──▶ teltonika-rms-mcp ──HTTPS + Bearer token──▶ RMS API

• Pagination: list tools take limit/offset, and fleet_summary walks all pages up to a safety cap.

• Rate limits and transient errors: HTTP 429 and 5xx responses are retried with backoff, honouring Retry-After.

• Async operations: some RMS actions return a meta.channel instead of a result. The client polls /status/channel/{channel} until the operation finishes, so the agent gets a single final answer.

• Errors are returned as readable messages with hints, for example a 403 that names the missing scope.

Known limitations

This is a prototype. Contributions are welcome.

• Endpoint coverage is intentionally small. Use rms_get to explore more endpoints, then promote the useful ones to proper tools.

• reboot_device runs the reboot command through POST /devices/{id}/command. A timeout in the result is expected, because the device drops its connection while it reboots.

• Field names in device payloads vary across models and RMS versions. fleet_summary tries several candidate keys for model, firmware, status and signal.

• On a device, connection_state is the last known mobile connection state, not whether RMS can reach the device right now. Use get_device_status for that.

• So far the test suite runs only against a mocked RMS. Reports from real fleets are very welcome.

Ideas for contributors

• More tools: device location, firmware update, config profiles, RMS Connect and remote-access links, hotspots, VPN hubs.

• OAuth2 support for multi-user and remote deployments.

• MCP resources for fleet snapshots, and prompts such as a "daily fleet health report".

• Batch actions with a dry-run preview and per-device confirmation.

Development

pip install -e ".[dev]"
pytest
ruff check .

The tests run a real in-memory MCP client session against a fake RMS API, so no token is needed.

Security notes

• Prefer a dedicated token with minimal scopes and, where possible, scoped to a single company.

• Start with RMS_READ_ONLY=true.

• Never commit your token. .env is git-ignored.

• An agent with write tools can affect real devices in the field. Keep a human in the loop.

License

MIT © Marcelo Muñoz