genieacs-mcp
✨ Was Sie erhalten
Typ | Wofür | MCP URI / Tool-ID |
Ressourcen | GenieACS-Daten schreibgeschützt abrufen |
|
Tools | Aktionen auf einem CPE über GenieACS ausführen |
|
Alles wird über einen einzigen JSON-RPC-Endpunkt (/mcp) bereitgestellt.
LLMs / Agenten können: initialize → readResource → listTools → callTool … und so weiter.
Related MCP server: router-mcp
🚀 Schnellstart (Docker Compose)
Folgen Sie den Anweisungen unter https://github.com/GeiserX/genieacs-container, es ist in der dortigen Docker-Compose-Datei enthalten.
📦 Installation via npm (stdio-Transport)
npx genieacs-mcpOder global installieren:
npm install -g genieacs-mcp
genieacs-mcpDies lädt das vorkompilierte Go-Binary für Ihre Plattform herunter und führt es mit stdio-Transport aus, kompatibel mit jedem MCP-Client.
🛠 Lokaler Build
git clone https://github.com/GeiserX/genieacs-mcp
cd genieacs-mcp
# (optional) create .env from the sample
cp .env.example .env && $EDITOR .env
go run ./cmd/server🔧 Konfiguration
Variable | Standard | Beschreibung |
| GenieACS NBI-Endpunkt (ohne abschließenden /) | |
| admin | GenieACS-Benutzername |
| admin | GenieACS-Passwort |
| (leer = HTTP) | Auf |
Fügen Sie diese in eine .env-Datei (aus .env.example) ein oder setzen Sie sie in der Umgebung.
Testen
Getestet mit Inspector und es funktioniert derzeit vollständig. Bevor Sie einen PR erstellen, stellen Sie sicher, dass sich dieser MCP-Server über dieses Medium korrekt verhält.
Es fehlt an Tests mit tatsächlichen MCP-Clients (Client-LLMs), daher reichen Sie bitte Ihre PRs ein, um die Beschreibungen zu verbessern, falls es die von diesem MCP-Server angebotenen Dienste nicht angemessen widerspiegelt.
Beispielkonfiguration für Client-LLMs:
{
"schema_version": "v1",
"name_for_human": "GenieACS-MCP",
"name_for_model": "genieacs_mcp",
"description_for_human": "Read data from GenieACS and run actions on CPEs (reboot, firmware update, parameter refresh).",
"description_for_model": "Interact with an Auto-Configuration-Server (ACS) that manages routers. First call initialize, then reuse the returned session id in header \"Mcp-Session-Id\" for every other call. Use readResource to fetch URIs that begin with genieacs://. Use listTools to discover available actions and callTool to execute them.",
"auth": { "type": "none" },
"api": {
"type": "jsonrpc-mcp",
"url": "http://localhost:8080/mcp",
"init_method": "initialize",
"session_header": "Mcp-Session-Id"
},
"logo_url": "https://raw.githubusercontent.com/GeiserX/genieacs-container/main/extra/logo.png",
"contact_email": "acsdesk@protonmail.com",
"legal_info_url": "https://github.com/GeiserX/genieacs-mcp/blob/main/LICENSE"
}Credits
GenieACS – das beste Open-Source-ACS
MCP-GO – moderne MCP-Implementierung
GoReleaser – schmerzfreie Multi-Arch-Releases
Betreuer
Mitwirken
Fühlen Sie sich frei, mitzumachen! Öffnen Sie ein Issue oder reichen Sie PRs ein.
GenieACS-MCP folgt dem Contributor Covenant Verhaltenskodex.
GenieACS-Ökosystem
Dieses Projekt ist Teil einer breiteren Palette von Tools für die Arbeit mit GenieACS:
Projekt | Typ | Beschreibung |
Docker + Helm | Produktionsbereites Multi-Arch-Docker-Image und Helm-Chart | |
Ansible-Collection | Dynamisches Inventar-Plugin und Geräteverwaltungsmodule | |
HA-Integration | Home Assistant-Integration für TR-069-Überwachung | |
n8n-Node | Workflow-Automatisierung für GenieACS | |
Service-Defs | Systemd/Supervisord-Service-Definitionen | |
Simulator | Docker-basierter GenieACS-Simulator zum Testen |
Andere MCP-Server von GeiserX
cashpilot-mcp — Überwachung von passivem Einkommen
duplicacy-mcp — Überwachung des Backup-Status
lynxprompt-mcp — KI-Konfigurations-Blueprints
pumperly-mcp — Kraftstoff- und EV-Ladepreise
telegram-archive-mcp — Telegram-Nachrichtenarchiv
Available Tools
12 toolsconnection_requestWake device (connection request)AIdempotent
Send a TR-069 connection request so a CPE device contacts GenieACS now instead of at its next periodic inform. Use it to run tasks that are already queued, or to apply a preset change without waiting. It queues nothing itself. Succeeds when the device answered; fails with ACS error 504 when the device is unreachable (offline, or behind NAT without STUN). Example: connection_request(device_id="202BC1-BM632w-000001").
Inputs: device_id (required).
delete_taskDelete queued taskADestructiveIdempotent
Remove a task from the GenieACS queue before the device runs it, for example a firmware download or reboot queued by mistake, or a faulted task you do not want retried. GenieACS already deletes a task once the device has run it, so every task you can see in genieacs://tasks/{device_id} is either waiting or faulted. Fails with ACS error 503 while the device is in a session with GenieACS; try again a few seconds later. Use retry_task instead to run a faulted task again. Example: delete_task(task_id="67abc123def4560012345678").
Inputs: task_id (required).
download_firmwarePush firmware or file to deviceADestructive
Tell a CPE device to download and apply a file stored on GenieACS: a firmware image, a configuration file or another file the device accepts. A wrong image can leave a device unusable, so check the file's metadata (genieacs://file/{name}: OUI, product class, version) against the device first. GenieACS queues a download task and sends a connection request at once; the transfer itself can take minutes after the tool returns. Check genieacs://tasks/{device_id} and genieacs://faults/{device_id} afterwards. Example: download_firmware(device_id="202BC1-BM632w-000001", file_id="firmware-v2.0.bin").
Inputs: file_id (required), device_id (required), filename. Returns: task, status, message, task_id, +1 more
get_parameterRead cached device parametersARead-onlyIdempotent
Read TR-069 parameter values GenieACS has cached for a device, without contacting the device: firmware version, serial number, uptime, WiFi SSID, IP addresses and so on. Values are what the device reported at its last inform or refresh, with a timestamp each; call refresh_parameter first when you need a value from the device now. Give one path or a comma-separated list; an object path such as "Device.WiFi" returns every cached leaf under it. Returns found=false for an unknown device id, and lists paths with no cached value under missing.
Inputs: device_id (required), parameter_path (required). Returns: found, missing, device_id, parameters
manage_presetCreate, replace or delete presetADestructiveIdempotent
Create, replace or delete a GenieACS preset. A preset is a fleet-wide rule: at their next inform, every device matching its precondition gets its configurations applied, so a broad precondition (or an empty one) reconfigures the whole fleet. Confirm the precondition and the devices it matches (search_devices with the same filter) before a put. action="put" creates or overwrites the preset with body; action="delete" removes it. body is a JSON object: weight (integer, higher wins), precondition (a MongoDB-style filter as a JSON string, e.g. "{"_tags":"office"}"), and configurations (an array of {type: "value" | "provision" | "add_object" | "delete_object", ...}). Example body: {"weight":0,"precondition":"{"_tags":"pilot"}","configurations":[{"type":"provision","name":"myScript"}]}. Read genieacs://presets/list first.
Inputs: name (required), action (required), body.
manage_provisionCreate, replace or delete provision scriptADestructiveIdempotent
Create, replace or delete a GenieACS provision script. A provision is JavaScript that GenieACS runs during the inform session of every device a preset applies it to, so replacing one changes how those devices are configured. Scripts use the GenieACS sandbox API (declare, commit, clear, ext, log); ext() calls extension scripts that run on the ACS host with full privileges, so treat a provision as code running on your ACS. action="put" uploads or overwrites the script (raw JavaScript, not JSON; GenieACS answers 400 on a syntax error); action="delete" removes it. Presets reference provisions by name. Read genieacs://provisions/list first. Example script: log("Device " + DeviceID.ID + " informed");
Inputs: name (required), action (required), script.
reboot_deviceReboot deviceADestructive
Reboot a CPE device through GenieACS. Use it when a device needs a restart, for example after a configuration change or to recover an unresponsive device. The device drops its service while it restarts. GenieACS queues the task and sends a connection request at once: status "done" means the device ran it in that session, "queued" means it runs at the device's next inform. A reboot does not confirm the device came back; read Device.DeviceInfo.UpTime (or InternetGatewayDevice.DeviceInfo.UpTime) with refresh_parameter afterwards. Example: reboot_device(device_id="202BC1-BM632w-000001").
Inputs: device_id (required). Returns: task, status, message, task_id, +1 more
refresh_parameterRefresh parameter from deviceAIdempotent
Ask a CPE device for the current value of a TR-069 parameter, or of every parameter under an object path, and store it in GenieACS. Use it when get_parameter's cached value may be stale. It changes nothing on the device. GenieACS queues a getParameterValues task and sends a connection request at once: status "done" means the fresh value is already stored, so read it with get_parameter; "queued" means it arrives at the device's next inform. Example: refresh_parameter(device_id="202BC1-BM632w-000001", parameter="Device.DeviceInfo.SoftwareVersion").
Inputs: device_id (required), parameter (required). Returns: task, status, message, task_id, +1 more
retry_taskRetry faulted taskAIdempotent
Run a faulted task again: GenieACS clears the task's fault, and the device runs the task at its next session. Read genieacs://faults/{device_id} first to see why it failed; retrying a task whose cause is unchanged faults again. A task that has not faulted is left as it is. Example: retry_task(task_id="67abc123def4560012345678").
Inputs: task_id (required).
search_devicesSearch devicesARead-onlyIdempotent
Find CPE devices in GenieACS with a MongoDB-style filter: by tag, manufacturer, model, firmware version, last inform time or any TR-069 parameter. It only reads. Examples: {"_tags":"office"}; {"InternetGatewayDevice.DeviceInfo.Manufacturer":"Huawei"} (GenieACS adds ._value to parameter paths); {"_lastInform":{"$lt":"2026-01-01T00:00:00Z"}} for devices silent since that date; {"_id":{"$regex":"^202BC1-"}}. Query operators such as $eq, $ne, $gt, $lt, $in, $nin, $exists, $regex, $and and $or work; $where, $function, $accumulator and $expr are refused, and a $regex pattern may be at most 256 characters. By default each device comes back as a summary (id, last inform, tags, manufacturer, product class, serial); ask for other fields with projection. Results come in pages of limit (default 50, at most 200); page with skip.
Inputs: query (required), skip, sort, limit, +1 more. Returns: more, skip, count, limit, +1 more
set_parameterSet device parametersADestructiveIdempotent
Write one or more TR-069 parameter values on a CPE device, overwriting the current values: WiFi SSID or key, periodic inform interval, management server URL, or any writable parameter. A wrong value can cut the device off (a wrong WAN or ACS URL setting, for example). parameter_values is a JSON array of [path, value] or [path, value, xsdType] tuples; xsd types include xsd:string, xsd:boolean, xsd:unsignedInt, xsd:int and xsd:dateTime, and GenieACS infers the type when it is omitted. Example: [["InternetGatewayDevice.LANDevice.1.WLANConfiguration.1.SSID","Lab-2","xsd:string"]]. GenieACS queues the task and sends a connection request at once: status "done" means the device applied it, "queued" means it runs at the next inform. A read-only or unknown parameter makes the device fault the task; see genieacs://faults/{device_id}. Read the current value with get_parameter first.
Inputs: device_id (required), parameter_values (required). Returns: task, status, message, task_id, +1 more
tag_deviceAdd or remove device tagADestructiveIdempotent
Add a tag to a CPE device or remove one. Tags group devices: presets match on them (precondition {"tags":"office"}) and search_devices finds by them. Adding or removing a tag can therefore make a preset apply to the device, or stop applying, at its next inform. Tags are case-sensitive. Use letters, digits, "-" and "": GenieACS rejects a tag with other characters (a "." for example) with a 404. Fails with ACS error 404 when the device id does not exist. Example: tag_device(device_id="202BC1-BM632w-000001", tag="office", action="add").
Inputs: tag (required), action (required), device_id (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 12 tools
Each tool targets a distinct resource+action, and subtle pairs are explicitly separated: get_parameter (cached) vs refresh_parameter (fresh from device), delete_task vs retry_task, manage_preset vs manage_provision. Several tools queue tasks, but their purposes (reboot, download firmware, set/refresh parameters) are clearly different, and connection_request is explicitly documented as queueing nothing.
Eleven of twelve tools follow a clean verb_noun snake_case pattern (get_parameter, set_parameter, delete_task, reboot_device, tag_device, search_devices, etc.). The outlier is connection_request, which drops the leading verb; manage_preset/manage_provision also fold create/update/delete into an action parameter rather than separate names, a minor inconsistency.
Twelve tools is well within the ideal range and each earns its place: device discovery, parameter read/write/refresh, task lifecycle, firmware, presets, provisions, tagging, and connection requests. Nothing feels redundant or missing for the apparent ACS-management scope.
The surface covers the core TR-069 lifecycle: discover/tag devices, read/write/refresh parameters, reboot, download firmware, manage tasks (delete/retry), and CRUD presets/provisions. Minor gaps remain—no tool to list or upload the files that download_firmware references, and no dedicated task/fault listing tool (deferred to resource URIs), which agents can partly work around.
Maintenance
Related MCP Connectors
Go MCP server for GitLab: 2 dynamic tools reach 1000+ REST/GraphQL actions. Free/CE, no paid tier.
An MCP server that provides an API to LLMs to manage their JumpCloud resources.
MCP server for OnceAsk, the AI-native current-address layer for people and agents.
Host any HTTP API as a standard MCP server; auto-distribute to 12+ mainstream agent platforms.
Related MCP Servers
- AlicenseNot gradedqualityNot gradedmaintenanceA high-performance Go-based MCP server that provides a microservice architecture for orchestrating diverse tools through gRPC and HTTP/REST APIs. Enables seamless integration of language-agnostic tools including ML capabilities, web search, calculations, and human interaction for intelligent agent workflows.2-
- AlicenseAqualityDmaintenanceMCP server for monitoring and controlling WiFi routers (OpenWrt) via SSH, enabling device listing, status checks, WiFi configuration, rebooting, and more.717 npmMIT
- AlicenseNot gradedqualityCmaintenanceProvider-agnostic MCP server for managing heterogeneous infrastructure (SSH, Proxmox VE, Virtualizor, Hetzner Cloud, Cloudflare) via a JSON inventory, exposing tools for VM/container management, DNS, firewalls, and SSH operations.MIT
- AlicenseBqualityBmaintenanceCommunity-maintained downstream MCP server for bounded AsusWRT and AsusWRT-Merlin administration over SSH.68MIT