Genieacs Mcp

genieacs-mcp 是适用于 GenieACS 的 MCP 服务。GenieACS 是一款开源 TR-069 ACS，用于管理路由器、ONT 和其他 CPE 设备。将它添加到 Claude Desktop、Cursor 或任何其他 MCP 客户端，然后用自然语言提问：昨晚哪些设备停止了上报？序列号为 000003 的设备运行什么固件？重启标记为 pilot 的设备。助手通过 GenieACS NBI 读取信息并执行操作，提供 7 个资源和 12 个工具；它是一个 Go 二进制文件，无需自带数据库。

功能

• 像询问同事一样查找设备：按标签、型号、固件、上次上报时间或任何 TR-069 参数查找（search_devices 接受 MongoDB 风格的筛选条件）。
• 将设备的完整参数树、任务和故障，以及 ACS 上的预设、配置和文件作为资源读取（genieacs://device/{id}、genieacs://devices/list 等）。
• 在聊天中重启设备、向设备推送固件、刷新或设置参数，或通过连接请求唤醒设备。
• 为设备添加标签、创建或删除预设和配置，以及删除或重试任务，帮助助手修复发现的问题。
• 每个工具的描述都说明其用途、限制和示例，让客户端无需你提供提示词就能选对工具。
• 读取与操作分明：search_devices、get_parameter 和 7 个资源仅用于读取；其他 10 个工具会在设备上排入任务或更改 ACS。每个工具的提示信息都会说明其行为，因此客户端可以在执行操作前征求你的确认。
• 只读模式：GENIEACS_READ_ONLY=true 仅提供两个读取工具和资源；GENIEACS_TOOLS=search_devices,reboot_device 则仅提供你指定的工具。
• 支持 MCP 2026-07-28 及所有更早版本，最早可追溯至 2024-11-05，因此新旧客户端都能通过 stdio 或无状态 HTTP 连接。
• 适合在笔记本电脑上安全运行：HTTP 传输仅监听本地回环地址，除非你设置地址和 bearer token；此外还会检查 Host 和 Origin，防范 DNS 重绑定攻击。
• 一个适用于 Linux、macOS 和 Windows 的静态 Go 二进制文件，支持 amd64 和 arm64；也可作为 npm 包（npx genieacs-mcp）和 Docker 镜像使用。

快速开始

你需要一个本机可以访问其 NBI（端口 7557）的 GenieACS；如果没有，使用该项目系列的演示堆栈，大约一分钟即可获得一个带模拟路由器的 ACS：

curl -fsSLO https://raw.githubusercontent.com/GeiserX/genieacs-container/main/docker-compose.yml
docker compose --profile testing up -d      # GenieACS + MongoDB + one simulated CPE, NBI on localhost:7557

然后，将服务添加到支持 mcpServers 块的客户端（Claude Desktop、Cursor、Claude Code；在 VS Code 中，.vscode/mcp.json 的键是 servers）：

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

同一服务在其他客户端中的配置：

# Claude Code
claude mcp add --transport stdio --env ACS_URL=http://localhost:7557 genieacs -- npx -y genieacs-mcp

# Docker, over stdio (any client that starts a command)
docker run -i --rm -e ACS_URL=http://host.docker.internal:7557 drumsergio/genieacs-mcp:v0.4.0

// VS Code, .vscode/mcp.json
{ "servers": { "genieacs": { "type": "stdio", "command": "npx", "args": ["-y", "genieacs-mcp"], "env": { "ACS_URL": "http://localhost:7557" } } } }

# Codex, ~/.codex/config.toml
[mcp_servers.genieacs]
command = "npx"
args = ["-y", "genieacs-mcp"]
env = { ACS_URL = "http://localhost:7557" }

当你询问“ACS 知道哪些设备？”而助手回答出设备 ID（例如演示堆栈中的 202BC1-BM632w-000000，或你自己的设备 ID）时，就说明配置成功了。Docker、HTTP 传输和本地构建的相关说明，请参阅入门指南。

文档

完整文档见 geiserx.github.io/genieacs-mcp。

• 入门指南：npm、Docker Compose、本地构建，以及首次交互示例
• 配置：所有环境变量、HTTP 传输的安全模型，以及 stdio 和 HTTP 的客户端配置
• 用法：7 个资源和 12 个工具及其参数、哪些工具会对设备执行操作，以及提示词示例
• 开发：测试、使用 MCP Inspector 试用服务，以及参与贡献
• 相关项目：GenieACS 项目系列、其他 MCP 服务，以及本服务的收录信息

相关项目

本项目已作为 io.github.GeiserX/genieacs-mcp 收录在官方 MCP Registry 中。它属于 GenieACS 项目系列，包括 genieacs-container（ACS 本身，提供 Docker 和 Helm，并将本服务作为 compose 配置档）、genieacs-sim-container、genieacs-ansible、genieacs-ha、genieacs-services 和 n8n-nodes-genieacs（已归档）。

许可证

GPL-3.0-or-later