Skip to main content
Glama

genieacs-nbi-mcp

CI npm License: Apache-2.0

Let your LLM look at your TR-069 fleet, without letting it touch a single CPE.

genieacs-nbi-mcp is a strictly read-only Model Context Protocol server for the GenieACS northbound interface (NBI). It helps ISP/NOC staff ask an AI assistant questions such as which ONTs have not informed for a week, why does this CPE fault on provisioning, what firmware is on file — using only HTTP GET.

Status: v0.1, not yet published to npm. Install from source or a release tarball until then. Independent project; not affiliated with GenieACS. Sibling of netscope-mcp.

Why read-only

The GenieACS NBI can reboot devices, factory-reset them, rewrite Wi-Fi settings and delete files. A hallucinated task is a customer outage. This server makes observation the only mode:

  • GET only. The HTTP verb is a constant in the client; there is no code path that sends anything else.

  • Guard before the network. POST/PUT/PATCH/DELETE, /devices/{id}/tasks, tag paths and the connection_request flag are refused by policy before a request is built. Unknown collections, .., double slashes and absolute URLs are refused too.

  • Secrets stay home. Wi-Fi keys, PPP/ACS passwords, SNMP communities and password-like assignments in provision scripts are masked; the NBI credentials are scrubbed from every output. Redaction is best-effort and based on parameter names (a heuristic, not a comprehensive guarantee); redact: false disables it.

  • Bounded. Row limits, output size limit, body cap, timeouts, no redirects followed.

The guard is one layer. Also give this server an NBI account/proxy that only allows GET (see SECURITY.md).

Related MCP server: netmiko-mcp

Quickstart

git clone https://github.com/tempatsimpanku-pixel/genieacs-mcp && cd genieacs-mcp
npm ci && npm run build

export GENIEACS_NBI_URL=http://acs.example.net:7557
# export GENIEACS_NBI_USER=noc GENIEACS_NBI_PASS=...   # only if the NBI needs basic auth
node dist/cli.js --check          # validates config and pings the NBI

Once published: npx genieacs-nbi-mcp --check.

MCP client entry (stdio):

{
  "mcpServers": {
    "genieacs": {
      "command": "npx",
      "args": ["-y", "genieacs-nbi-mcp"],
      "env": { "GENIEACS_NBI_URL": "http://acs.example.net:7557" }
    }
  }
}

HTTP mode (shared server, bearer token ≥ 32 chars, loopback by default):

GENIEACS_MCP_TOKEN="$(openssl rand -hex 32)" genieacs-nbi-mcp --http 127.0.0.1:8080

Tools

Tool

NBI call

Purpose

acs_devices

GET /devices

List/search devices (query, projection, limit, skip, sort)

acs_device

GET /devices?query={"_id":…}

One device by exact _id

acs_tasks

GET /tasks

Queued operations (optionally per device)

acs_faults

GET /faults

Failed sessions / provisions

acs_files

GET /files

Firmware and config file metadata

acs_presets

GET /presets

Preset definitions

acs_provisions

GET /provisions

Provision scripts (secrets masked)

acs_read

GET <path>

Raw GET on a readable path; any other verb is refused

Details and examples: docs/TOOLS.md. Configuration: docs/CONFIG.md.

Compatibility

Component

Supported

Node.js

>= 20 (CI: 22, 24; runtime smoke on 20)

GenieACS NBI

1.2.x REST API (/devices, /tasks, /faults, /files, /presets, /provisions, /virtualparameters, /objects) — tested against a mock; verify on your version with --check

MCP transports

stdio, Streamable HTTP (stateless, JSON responses)

MCP clients

any client that speaks MCP 2025 revisions (Claude, Codex, Cursor, …)

Write operations

none, by design

Development

npm ci && npm run typecheck && npm run lint && npm test && npm run build

Tests use a local mock NBI; they never contact a real ACS. See CONTRIBUTING.md.

License

Apache-2.0. See LICENSE and NOTICE. Indonesian version: README.id.md.

Available Tools

8 tools
acs_deviceDevice detailA
Read-onlyIdempotent

Read one device by its exact _id (e.g. "202BC1-BM632w-000001"; GET /devices?query={"_id":…}). Pass projection (comma separated parameter paths) unless you really need the full parameter tree. Secrets (Wi-Fi keys, passwords, communities) are masked.

Inputs: id (required), projection.

acs_devicesList / search devicesA
Read-onlyIdempotent

List or search CPE/ONT devices known to the ACS (GET /devices). Use query to filter and ALWAYS pass a projection to keep rows small. Examples: {"_id":{"$regex":"ZTE"}} · {"_lastInform":{"$lt":"2026-10-01T00:00:00Z"}} (stale devices) · {"VirtualParameters.pppoeUsername":"user@isp"}. total is the number of matches.

Inputs: skip, sort, limit, query, +1 more.

acs_faultsFaultsA
Read-onlyIdempotent

List ACS faults (GET /faults): failed sessions or provisions per device/channel, with code, message, retry count and timestamps. Start here for "why does this ONT not provision".

Inputs: skip, sort, limit, query, +2 more.

acs_filesFirmware / config filesA
Read-onlyIdempotent

List files stored in the ACS (GET /files): firmware images and vendor config files with filename, fileType, OUI, productClass and version. Metadata only; file contents are not downloadable here.

Inputs: skip, sort, limit, query, +2 more.

acs_presetsPresetsB
Read-onlyIdempotent

List presets (GET /presets): which provisions run for which devices (channel, weight, precondition, events).

Inputs: skip, sort, limit, query, +1 more.

acs_provisionsProvisionsA
Read-onlyIdempotent

List provision scripts (GET /provisions). Script bodies are returned as stored, with password-like assignments masked.

Inputs: skip, sort, limit, query, +1 more.

acs_readRaw GET on the NBIA
Read-onlyIdempotent

Escape hatch: GET any readable NBI path, e.g. "/devices?limit=3&projection=id" or "/virtualparameters". Allowed collections: /devices /tasks /faults /files /presets /provisions /virtualparameters /objects. Only GET is sent; POST/PUT/PATCH/DELETE, /devices/{id}/tasks, tag changes and the connection_request flag are refused by policy. Prefer the dedicated acs* tools.

Inputs: path (required), method.

acs_tasksPending tasksA
Read-onlyIdempotent

List queued ACS tasks (GET /tasks): operations waiting for a device to connect. A growing backlog on one device often means it is offline or unreachable. Read-only: tasks can not be created or deleted here.

Inputs: skip, sort, limit, query, +2 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 8 tools

    Disambiguation4/5

    The tools mostly map cleanly to distinct ACS collections/actions. The singular/plural pair acs_devices vs acs_device is clearly differentiated by description, though acs_read intentionally overlaps all dedicated read tools as an escape hatch.

    Naming Consistency4/5

    All tools share the acs_ prefix and use predictable resource-oriented names, with singular/plural distinctions for single vs list operations. acs_read is the only verb-style outlier, but its escape-hatch role is explicit.

    Tool Count5/5

    Eight tools is well-scoped for a read-only ACS NBI surface. Each tool corresponds to a meaningful endpoint or collection, and the generic read escape hatch avoids adding many redundant per-collection variants.

    Completeness4/5

    The read-only surface covers the main ACS collections: devices, tasks, faults, files, presets, provisions, plus a generic GET escape hatch for virtualparameters/objects. Write operations and task creation are intentionally excluded, and file contents are not downloadable, but these are clear policy limitations rather than accidental gaps.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables secure, read-only monitoring of Cisco Meraki networks, allowing AI agents to query real-time information on organizations, networks, devices, clients, and traffic without risk of configuration changes.
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Provides read-only SSH access to network devices (routers, switches, firewalls) with command allow/deny policies, nt-templates output parsing, and an audit trail, enabling an AI agent to query device state securely.
      10
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides read-only access to Tactical RMM, enabling agent searches, detailed agent information, audit log queries, and execution of information-gathering PowerShell scripts on agents, with Entra ID authentication and a strict read-only guard.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Provides read-only, multi-vendor network device interaction, configuration auditing against vendor-guide rules, and safe diffing of proposed changes for AI agents to inspect and analyze network infrastructure without any commit or write capability.
      1
      Apache 2.0