genieacs-mcp
✨ 你将获得什么
类型 | 用途 | MCP URI / 工具 ID |
资源 | 只读获取 GenieACS 数据 |
|
工具 | 通过 GenieACS 在 CPE 上调用操作 |
|
所有内容均通过单个 JSON-RPC 端点 (/mcp) 公开。
LLM / 代理可以:initialize → readResource → listTools → callTool ……以此类推。
Related MCP server: router-mcp
🚀 快速入门 (Docker Compose)
请遵循 https://github.com/GeiserX/genieacs-container 中的说明,该项目已包含在其中的 docker compose 文件中。
📦 通过 npm 安装 (stdio 传输)
npx genieacs-mcp或者全局安装:
npm install -g genieacs-mcp
genieacs-mcp这将为你的平台下载预构建的 Go 二进制文件,并以 stdio 传输方式运行它,兼容任何 MCP 客户端。
🛠 本地构建
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🔧 配置
变量 | 默认值 | 描述 |
| GenieACS NBI 端点(末尾不带 /) | |
| admin | GenieACS 用户名 |
| admin | GenieACS 密码 |
| (空 = HTTP) | 设置为 |
将它们放入 .env 文件(从 .env.example 复制)或在环境中设置它们。
测试
已使用 Inspector 进行测试,目前完全可用。在提交 PR 之前,请确保此 MCP 服务器通过该媒介表现良好。
缺乏与实际 MCP 客户端(客户端 LLM)的测试,因此如果它未能充分匹配此 MCP 服务器提供的服务,请提交 PR 以改进描述。
客户端 LLM 的配置示例:
{
"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"
}鸣谢
GenieACS – 最好的开源 ACS
MCP-GO – 现代 MCP 实现
GoReleaser – 轻松实现多架构发布
维护者
贡献
欢迎加入!提交 issue 或提交 PR。
GenieACS-MCP 遵循 Contributor Covenant 行为准则。
GenieACS 生态系统
该项目是用于处理 GenieACS 的更广泛工具集的一部分:
项目 | 类型 | 描述 |
Docker + Helm | 生产就绪的多架构 Docker 镜像和 Helm chart | |
Ansible Collection | 动态清单插件和设备管理模块 | |
HA 集成 | 用于 TR-069 监控的 Home Assistant 集成 | |
n8n 节点 | GenieACS 的工作流自动化 | |
服务定义 | Systemd/Supervisord 服务定义 | |
模拟器 | 用于测试的基于 Docker 的 GenieACS 模拟器 |
GeiserX 的其他 MCP 服务器
cashpilot-mcp — 被动收入监控
duplicacy-mcp — 备份健康状况监控
lynxprompt-mcp — AI 配置蓝图
pumperly-mcp — 燃油和电动汽车充电价格
telegram-archive-mcp — Telegram 消息存档
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