Genieacs MCP

What GeiserX/genieacs-mcp does

GeiserX/genieacs-mcp exposes GenieACS through the Model Context Protocol. GenieACS is a TR-069 Auto Configuration Server for routers, ONTs, and other CPE devices. The MCP server uses the ACS NBI rather than maintaining a separate device database, allowing an MCP client to inspect inventory and request device operations from the same system used for normal GenieACS management.

Its read capabilities include device searches using MongoDB-style filters, cached parameter lookup, and access to device documents, task data, faults, presets, provisions, and files through seven genieacs:// resources. Write and operational capabilities include connection requests, reboots, firmware or file downloads, parameter refreshes and updates, device tagging, preset and provision management, and task deletion or retry.

How it works

The server translates MCP tool calls into GenieACS NBI requests. Searches can filter by tags, manufacturer, model, firmware, last inform time, or stored TR-069 paths. get_parameter reads values already held by GenieACS, while refresh_parameter queues a request for the CPE to report a current value. Device actions such as rebooting, downloading firmware, and setting parameters are generally asynchronous tasks executed when the CPE next contacts the ACS.

A connection request can prompt an immediately reachable CPE to start a CWMP session, but it does not itself create a task. Tasks can be inspected through resources, removed while pending, or retried after a fault. Presets and provisions change ACS behavior for later device inform sessions rather than applying changes immediately.

Setup and configuration

A reachable GenieACS NBI is required; the example configuration uses http://localhost:7557. The server can be launched with the npm package through npx genieacs-mcp, built as a local Go binary, or run with Docker. Configure an MCP client with an mcpServers entry and set ACS_URL in its environment:

{
  "mcpServers": {
    "genieacs": {
      "command": "npx",
      "args": ["-y", "genieacs-mcp"],
      "env": { "ACS_URL": "http://localhost:7557" }
    }
  }
}

The documented client examples include Claude Desktop, Cursor, Claude Code, and VS Code. VS Code uses a servers key in .vscode/mcp.json rather than mcpServers. A demo stack can provide GenieACS, MongoDB, and a simulated CPE through Docker Compose, with the NBI exposed on local port 7557.

Tools and capabilities

• Search devices with MongoDB comparison and matching operators.
• Read cached TR-069 values or request parameter refreshes.
• Set writable parameters, reboot devices, request connections, and queue firmware or file downloads.
• Add or remove device tags for grouping and preset targeting.
• Create, replace, or delete presets and JavaScript provision scripts.
• Delete pending tasks or retry tasks that contain faults.

Limitations and notes

Cached values may be stale, and a parameter that GenieACS has never collected is unavailable through get_parameter. Refreshes, reboots, downloads, and parameter changes are asynchronous; completion must be checked through later device or task data. Connection requests require the CPE to be reachable from the ACS, so NAT, offline devices, or blocked ports can prevent them from working.

Only pending tasks can be deleted, and only faulted tasks can be retried. Writable parameter support depends on the CPE. Provision scripts run in the GenieACS sandbox with a limited API and cannot make arbitrary HTTP requests or access the filesystem. The server has no read-only mode, so MCP client approval prompts should remain enabled when exposing it to an assistant.