genieacs-nbi-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@genieacs-nbi-mcp which ONTs haven't informed in the last 7 days?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
genieacs-nbi-mcp
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 theconnection_requestflag 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: falsedisables 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 NBIOnce 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:8080Tools
Tool | NBI call | Purpose |
|
| List/search devices ( |
|
| One device by exact |
|
| Queued operations (optionally per device) |
|
| Failed sessions / provisions |
|
| Firmware and config file metadata |
|
| Preset definitions |
|
| Provision scripts (secrets masked) |
|
| 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 ( |
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 buildTests 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 toolsacs_deviceDevice detailARead-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 devicesARead-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_faultsFaultsARead-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 filesARead-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_presetsPresetsBRead-onlyIdempotent
List presets (GET /presets): which provisions run for which devices (channel, weight, precondition, events).
Inputs: skip, sort, limit, query, +1 more.
acs_provisionsProvisionsARead-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 NBIARead-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 tasksARead-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
Scored across 8 tools
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.
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.
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.
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
Related MCP Connectors
Read-only local AI advice, shared reports and website audits. No PC scan or local actions.
Safe, read-only Postgres and MySQL access for AI agents. Audit log + column-level controls.
Read-only MCP access to a documented IT fleet: state, changes, posture. 15 tools.
Read-only finance and operations controls for AI agents with evidence and safe next actions.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables 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
- AlicenseAqualityDmaintenanceProvides 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.10MIT
- AlicenseNot gradedqualityDmaintenanceProvides 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
- AlicenseNot gradedqualityBmaintenanceProvides 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.1Apache 2.0