# GeiserX/genieacs-mcp [Health: Active]

**Category:** 🏭 Industrial & IoT  
**Repository:** https://github.com/GeiserX/genieacs-mcp  
**GitHub Stars:** 19  
**npm Downloads (last month):** 642  
**Views:** 8  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/geiserx-genieacs-mcp

## Description
Go-based MCP server that bridges any GenieACS (TR-069 ACS) instance, exposing device data, firmware management, and CPE actions (reboot, parameter refresh, firmware download) over JSON-RPC. Docker image available.

## Tools
Capabilities this server exposes over MCP:

- **connection_request** — Send a connection request to wake a CPE device without waiting for its periodic inform. Use this tool when you need the device to contact the ACS immediately, for example to execute pending tasks, apply preset changes, or force a parameter refresh. This sends an HTTP connection request to the CPE's management URL as configured in the TR-069 connection request mechanism. Returns 200 on success (the CPE acknowledged the request) or 504 if the CPE is unreachable (behind NAT, offline, or firewall blocking the connection request port). Example: connection_request(device_id="00236A-SmartRG585-SMRT00236a42"). Limitations: the CPE must be network-reachable from the ACS for connection requests to work. Devices behind NAT without STUN/NAT traversal configured will not respond. This does not queue a task — it only triggers the CPE to initiate a CWMP session.
- **delete_task** — Delete a pending task from the GenieACS task queue. Use this tool to cancel a task that was queued but has not yet been executed by the CPE, such as a mistakenly queued firmware download or an unwanted reboot. The task_id is the _id field from the task document, obtainable via the genieacs://tasks/{id} resource. Returns a 503 error if the device is currently in an active CWMP session (the task cannot be deleted while the device is communicating with the ACS). Example: delete_task(task_id="67abc123def456"). Limitations: only pending tasks can be deleted. Completed or in-progress tasks cannot be removed. Use retry_task instead if the task faulted and you want to re-run it.
- **download_firmware** — Push a firmware image or configuration file to a CPE device via GenieACS TR-069 download mechanism. Use this tool to initiate an OTA firmware upgrade or to push any file (config backups, supplementary data) to a device. The file must already be uploaded to GenieACS — use genieacs://file/{name} to inspect available files. Returns the raw JSON response from the ACS confirming the download task was queued. Limitations: the download is asynchronous — the ACS queues the task and the CPE fetches the file on its next session (periodic inform or connection request). Large firmware files may take minutes to transfer. Verify success by checking genieacs://tasks/{device_id} after allowing time for the transfer. Example: download_firmware(device_id="00236A-SmartRG585-SMRT00236a42", file_id="firmware-v2.0.bin").
- **get_parameter** — Read specific TR-069 parameter values from the GenieACS cache for a device without contacting the CPE. Use this tool to quickly retrieve known parameter values such as firmware version, serial number, uptime, WiFi SSID, or IP addresses. This reads the last-known values stored in the ACS database — the data may be stale if the device has not informed recently. Use refresh_parameter first if you need a guaranteed fresh value from the CPE. The parameter_path can be a single parameter (e.g. "Device.DeviceInfo.SoftwareVersion") or a comma-separated list for multiple parameters. Returns the matching device document fields as JSON. Limitations: only returns data that the ACS has previously collected. If a parameter has never been read from the CPE, it will not appear in the response.
- **manage_preset** — Create, update, or delete a GenieACS preset. Presets define automatic configuration rules that are applied to CPE devices matching a precondition filter. Use action="put" to create or overwrite a preset, providing the full JSON body with weight, precondition, and configurations. Use action="delete" to remove a preset by name. A preset body should contain: weight (integer priority), precondition (a stringified MongoDB-style JSON query, e.g. "{\"_tags\":\"office\"}"), and configurations (array of objects with type "value", "provision", "add_object", or "delete_object"). Example body: {"weight":0,"precondition":"{\"_tags\":\"test\"}","configurations":[{"type":"provision","name":"myScript"}]}. Preset names cannot contain dots. Use genieacs://presets/list to view existing presets before making changes. Limitations: changes take effect on the next CPE inform, not immediately.
- **manage_provision** — Create, update, or delete a GenieACS provision script. Provision scripts are JavaScript functions that run on the ACS during a device's inform session to dynamically configure CPEs. Use action="put" to upload a new provision script or overwrite an existing one. The script argument must be raw JavaScript source code (not JSON). Use action="delete" to remove a provision script by name. GenieACS validates the script syntax on upload — a 400 error means the JavaScript has a syntax error. Provision scripts are referenced by name in presets (via configurations of type "provision"). Use genieacs://provisions/list to view existing scripts before making changes. Example script: log("Device " + args[0] + " informed"); Limitations: provision scripts execute server-side in the GenieACS sandbox with a limited API (declare, commit, ext, log). They cannot make arbitrary HTTP calls or access the filesystem.
- **reboot_device** — Reboot a CPE device through the GenieACS TR-069 ACS. Use this tool when a device needs to be restarted, for example after a configuration change, firmware update, or to recover from an unresponsive state. The device must exist in the GenieACS inventory — use genieacs://devices/list to discover valid IDs. Returns the raw JSON response from the ACS confirming the task was queued. Limitations: the reboot is asynchronous — the task is queued on the ACS and executed the next time the CPE contacts the ACS (via its periodic inform or a connection request). There is no confirmation that the device actually rebooted. Example: reboot_device(device_id="00236A-SmartRG585-SMRT00236a42").
- **refresh_parameter** — Request a CPE device to report the current value of a specific TR-069 parameter via GenieACS. Use this tool when you need an up-to-date reading of a device parameter — for example, checking the current firmware version, uptime, WiFi SSID, or any CWMP data model path. The refreshed value is stored in the GenieACS device document and can be read afterwards via genieacs://device/{id}. Returns the raw JSON response from the ACS confirming the refresh task was queued. Limitations: the refresh is asynchronous — the value is updated when the CPE next contacts the ACS. Only one parameter path can be refreshed per call; use the full dotted TR-069 object path. Example: refresh_parameter(device_id="00236A-SmartRG585-SMRT00236a42", parameter="Device.DeviceInfo.SoftwareVersion").
- **retry_task** — Retry a faulted task in GenieACS. Use this tool when a previously queued task (reboot, firmware download, parameter set, etc.) has failed and you want to re-attempt it. The task_id is the _id field from the task document, obtainable via the genieacs://tasks/{id} resource — look for tasks with fault information. This clears the fault and re-queues the task for execution on the next CPE inform. Example: retry_task(task_id="67abc123def456"). Use genieacs://faults/{id} to understand why the task originally failed before retrying. Limitations: only faulted tasks can be retried. Retrying a non-faulted task has no effect.
- **search_devices** — Search for CPE devices in GenieACS using MongoDB-style query filters. Use this tool to find devices by tag, manufacturer, model, firmware version, last inform time, or any other TR-069 parameter stored in the ACS. The query argument is a JSON string using MongoDB query syntax. Examples: {"_tags":"office"} to find devices tagged "office", {"InternetGatewayDevice.DeviceInfo.Manufacturer._value":"Huawei"} to find Huawei devices, {"_lastInform":{"$lt":"2024-01-01T00:00:00Z"}} to find devices that haven't informed since 2024. For non-underscore-prefixed parameter paths, GenieACS automatically appends "._value" to the query, so you can also query as {"InternetGatewayDevice.DeviceInfo.Manufacturer":"Huawei"}. Returns a JSON array of matching device documents. Use the limit argument to control the maximum number of results (default 50). Limitations: complex aggregation queries are not supported — only standard MongoDB comparison operators ($eq, $ne, $gt, $lt, $gte, $lte, $regex, $in, $nin, $exists).
- **set_parameter** — Set one or more TR-069 parameter values on a CPE device through GenieACS. Use this tool to change device configuration such as WiFi SSID, management server URL, periodic inform interval, or any writable TR-069 parameter. The parameter_values argument must be a JSON array of tuples, where each tuple is [parameterPath, value] or [parameterPath, value, xsdType]. Example: [["InternetGatewayDevice.LANDevice.1.WLANConfiguration.1.SSID","MySSID","xsd:string"]]. Valid xsd types include xsd:string, xsd:boolean, xsd:unsignedInt, xsd:int, xsd:dateTime. If the type is omitted, GenieACS infers it from the value. The task is queued and a connection request is sent to the CPE for immediate execution. Returns the raw ACS JSON response confirming the task. Limitations: the CPE must be reachable for immediate execution; otherwise the task remains queued until the next periodic inform. Not all parameters are writable — the CPE will fault if you attempt to set a read-only parameter. Use refresh_parameter or genieacs://device/{id} first to discover valid parameter paths.
- **tag_device** — Add or remove a tag on a CPE device in GenieACS. Tags are labels used to group devices for preset matching, bulk operations, and organizational purposes. Use action="add" to tag a device and action="remove" to untag it. Tags are referenced in preset preconditions (e.g. {"_tags":"office"}) to target specific device groups for automatic configuration. The device must exist in GenieACS — returns a 404 error if the device ID is invalid. Example: tag_device(device_id="00236A-SmartRG585-SMRT00236a42", tag="office", action="add"). Use search_devices with a _tags filter to verify tag assignment after modification. Limitations: tag names are case-sensitive strings. There is no built-in tag listing — use search_devices or genieacs://devices/list to discover existing tags on devices.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "genieacs-mcp": {
    "command": "npx",
    "args": ["-y","genieacs-mcp"],
    "env": {
      "ACS_URL": ""
    }
  }
}
```

**Requires environment variables:** `ACS_URL` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## 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:

```json
{
  "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.

_Full upstream README: https://allmcps.com/mcp/geiserx-genieacs-mcp/readme_