@reidar80/telemator-mcp

A read-only Model Context Protocol server for Telemator, the network documentation system that records a fiber operator's physical plant — points, trenches, cables and their individual cores, circuits and active equipment.

It sits between a model (Claude, Copilot, or an Azure AI Foundry agent) and the Telemator API, and it exists so that a fiber delivery assessment can be built from what is actually documented in the network, rather than guessed.

Built and maintained by Fortytwo Technologies.

This is decision support. Everything here reads. There is no code in this package that can modify Telemator. Any assessment of cost, complexity or feasibility built from these reads is material for a human planner to review — it is not an operational decision.

Install

npm install -g @reidar80/telemator-mcp

Requires Node 24 or newer.

Quick start

export TELEMATOR_MODE=gateway
export TELEMATOR_BASE_URL=https://telemator.example.no
export TELEMATOR_USERNAME=your-api-user
export TELEMATOR_PASSWORD=your-api-password

# See what would be registered, without contacting Telemator at all
telemator-mcp --list-tools

# Run on stdio, for a desktop MCP client
telemator-mcp

Claude Desktop / Claude Code

{
  "mcpServers": {
    "telemator": {
      "command": "telemator-mcp",
      "env": {
        "TELEMATOR_MODE": "gateway",
        "TELEMATOR_BASE_URL": "https://telemator.example.no",
        "TELEMATOR_USERNAME": "your-api-user",
        "TELEMATOR_PASSWORD": "your-api-password"
      }
    }
  }
}

Remote / Foundry

MCP_HTTP_PORT=8931 telemator-mcp-http
# MCP on http://localhost:8931/mcp, health on /health

Set MCP_HTTP_AUTH_TOKEN and require Authorization: Bearer <token>. Read the governance note under Deployment shapes before exposing this anywhere real.

The one thing to understand before using this

An unresolved read is not an absence.

TeleREST answers 404 both for "no such resource" and for "this list matched nothing". A gateway answers 404 for an unmapped route, and a reverse proxy answers 404 for its own reasons. If a failed lookup is read as "no fiber here", the result is a confident, wrong feasibility answer — which is the single worst thing a planning assistant can produce.

So every tool returns an envelope with an explicit verdict:

{
  "status": "present",              // there is data, in `data`
  "data":   { "End": "P0001" },
  "meta":   { "instanceState": "serving", "truncated": false }
}

{
  "status":  "absent",              // Telemator answered: there is nothing
  "absence": {
    "reason":  "empty-result",
    "checked": ["coordinates 69.7, 18.88 (WGS84 degrees) within 250 m"]
  }
}

{
  "notice":  "TELEMATOR_READ_UNKNOWN - this read did not complete. It is NOT evidence that the data is missing...",
  "status":  "unknown",             // we do not know, and must not pretend to
  "problem": { "reason": "timeout", "retryable": true, "hint": "..." }
}

absent always says what was searched, so a reader can judge whether the search was wide enough. unknown leads with a sentinel, because a hint buried three levels down gets summarised away as "nothing found".

A 404 is only ever read as absent when the body is empty (which is what TeleREST's own not-found carries, unlike a framework error page), a Server header matches the hop we confirmed, a probe has positively established that the instance is serving, the endpoint is not an unproven experimental one — and TELEMATOR_404_SEMANTICS=absent has been set deliberately. The default is unknown: fail closed until the instance's real 404 behaviour has been captured.

telemator_check_connection reports instanceState. If it is not serving, treat every negative result from every other tool as unresolved.

Coordinate systems

Telemator stores the UTM northing in a column called latitude and the UTM easting in one called longitude, with the zone in utmzone. A real row reads latitude: 7737238.2, longitude: 650258.1, utmzone: "33W" — a street address in Troms, not a point in the Arctic Ocean at 7.7 million degrees north.

Meanwhile trace geometry (polylinem) is WKT in WGS84 longitude/latitude degrees, and geometry is EWKB in EPSG:3857.

This server never hands a model a bare latitude/longitude pair for projected metres. telemator_get_point_location returns:

{
  "coordinate": {
    "crs": "utm-metres",
    "zone": "33W",
    "eastingMetres": 650258.1,
    "northingMetres": 7737238.2,
    "note": "Projected metres, not degrees. ..."
  }
}

telemator_find_nearest_fiber takes degrees. Reproject before passing one to the other. The telemator://crs resource says all of this to the model directly.

Tools

Grouped into toolsets. core, planning and geodata are enabled by default; select with TELEMATOR_TOOLSETS.

core — inventory reads

| Tool | Purpose | |---|---| | telemator_check_connection | Is Telemator reachable, and is it really Telemator answering? | | telemator_resolve_id | Translate a local alias into a Telemator ID | | telemator_get_point / telemator_search_points | Points: manholes, cabinets, customer terminations | | telemator_get_trace / telemator_search_traces | Traces: trenches and the ducts in them | | telemator_get_cable / telemator_search_cables | Cables, and with includeRouting, per-core occupancy | | telemator_get_circuit / telemator_get_circuit_routing / telemator_search_circuits | Circuits and their end-to-end paths | | telemator_get_equipment / telemator_search_equipment | Active equipment, cards and ports | | telemator_count_free_ports | Spare ports in a point or a device |

planning — the delivery assessment

All four sit on endpoints the vendor marks experimental, built for specific customers. They may be absent from a given Telemator build, and a 404 from one that has never succeeded is reported as "not available here" rather than "no data".

| Tool | Purpose | |---|---| | telemator_find_nearest_fiber | Termination points near a location, with the circuits in them. Where an assessment starts. | | telemator_suggest_routes | Telemator's own trace and duct suggestions for a cable | | telemator_trace_circuit_upstream | Follow a PON circuit through splitters to the central node | | telemator_list_cable_traces | The ordered trace list for a cable, with the vendor's Norwegian labels kept verbatim |

geodata — coordinates and geometry (gateway only)

The only source of coordinates anywhere in this API: TeleREST exposes none.

| Tool | Purpose | |---|---| | telemator_get_point_location | Address, cadastre and CRS-labelled coordinates | | telemator_get_trace_geometry | Route line as WKT, recorded length, trench depth | | telemator_get_cable_termination | Which cores land where, with the isdraft flag | | telemator_find_points_by_address | Address search (% is a wildcard) |

Opt-in toolsets

| Toolset | Contents | Why it is off | |---|---|---| | database | telemator_query_table | Direct table SELECT. Restricted to allow-listed tables and verified columns; prefer the geodata tools. | | custom | telemator_run_custom_query | Runs SQL configured server-side that we have not reviewed. Unregistered unless aliases are configured. | | faults | telemator_locate_core_fault | Fault management is outside the planning scope. | | print | telemator_generate_report | Reports are large and often binary. | | customers | telemator_get_customer, telemator_search_customers | Personal data. A delivery assessment is about infrastructure at a location, not who lives there. Confirm a lawful basis first. | | draft | telemator_preview_draft_proposal | Builds the payload a draft proposal would write. Makes no network call. |

Not implemented, deliberately

There is no DELETE anywhere in this package, no PUT, no as-built mutation, no splice operation, and no bulk purge. Not guarded — absent. A test asserts the source contains none of them. A 428 (Telemator asking a question) is surfaced for a person to answer, never auto-accepted.

Resources and prompt

• telemator://tables — the queryable tables and their verified columns. This is what makes telemator_query_table usable without a model guessing column names.
• telemator://crs — the coordinate-system note above.
• assess_fiber_delivery — a prompt framing an assessment with a tool order that works.

Configuration

Every value is settable programmatically; the CLIs read the environment. --help prints the full list; the ones worth knowing:

| Variable | Default | Notes | |---|---|---| | TELEMATOR_MODE | gateway | gateway for the Micado API; direct for a bare TeleREST instance (no /query, so no coordinates) | | TELEMATOR_BASE_URL | — | Required. Credentials embedded in the URL are rejected. | | TELEMATOR_USERNAME / _PASSWORD | — | Gateway JWT login | | TELEMATOR_404_SEMANTICS | unknown | Fail closed. See above before changing. | | TELEMATOR_MAX_CONCURRENCY | 4 | Telemator is one process over a desktop database. Raising this can stall the planners' own session. | | TELEMATOR_TOOLSETS | core,planning,geodata | | | TELEMATOR_PII_MODE | off | minimal returns customer id and name only | | TELEMATOR_SOURCE_SYSTEM | telemator-mcp | Recorded in Telemator's change log as the acting system | | TELEMATOR_LOG_LEVEL | info | Logs go to stderr; stdout is the JSON-RPC channel |

Deployment shapes

In a host application (the governed path). Import from @reidar80/telemator-mcp/core, which has no fastmcp in its import graph, and register each capability through your own governed tool mechanism, so that your policy, scopes and kill-switch apply to every call. A worked example is in src/adapters/README.md, which ships in the package.

import { allCapabilities, createTelematorClient } from '@reidar80/telemator-mcp/core';

As a standalone server. Convenient for development and for binding a remote MCP client to an HTTP endpoint. Be clear-eyed about it: a shared bearer token and per-tool access predicates are the whole of the authorization story. There is no external policy engine and no kill-switch. That is a development and integration path, not a production one.

Verify against your own instance before trusting it

This package was written against vendor documentation, without network access to a live Telemator instance. Every schema is therefore a working contract, not observed behaviour. Check these first, roughly in this order:

1. What the 404s actually look like — status, Server, Content-Type and body for three cases: an unknown route, a known route matching nothing, and a missing resource by ID. This decides whether TELEMATOR_404_SEMANTICS=absent is safe.
2. Whether your points carry coordinates at all. If EndReg.latitude is unpopulated, nearest-fiber search returns nothing however good the code is.
3. The JWT header form and real token lifetime. The gateway documentation says seven days; its own sample token says 24 hours. This client trusts the exp claim.
4. Which experimental /fn/* endpoints exist on your build, and what they return for no match — 404 or an empty 200.
5. Your TeleREST version, which decides the report response shape, and that the Route or Automation module licence is active. Without it the API is closed.
6. Whether IDs containing / or \ survive your reverse proxy. If not, set TELEMATOR_ID_ENCODING=base64url.

telemator_check_connection answers several of these in one call.

Development

pnpm install
pnpm verify   # lint, format, typecheck, coverage, build, spec lint, package check

The package is ESM-only. It declares engines.node: ">=24", and Node 24 can require() an ES module, so a CommonJS host on a recent Node can still consume it. It deliberately does not declare main/types, which would advertise a legacy resolution path it cannot honour — so attw runs with --profile esm-only.

The test suite installs a fetch that throws, so no test can reach a network. HTTP behaviour is driven through an injected fetch stub with recorded calls.

On Windows, corepack enable is not needed and will fail without an elevated shell, because it writes shims into the Node installation directory. npm i -g pnpm is enough: the packageManager pin in the workspace root is honoured by pnpm itself. Two conventions follow from supporting Windows and are worth keeping: npm runs lifecycle scripts through cmd.exe, so scripts on the publish path stay free of POSIX-shell commands (hence scripts/clean.mjs rather than rm -rf), and the repo pins LF via .gitattributes, without which a CRLF checkout fails format:check on every file.

Licence

Apache-2.0. Telemator and TeleREST are products of MX Data; this package is an independent client and is not affiliated with or endorsed by them.