Vyos MCP Go

vyos mcp去

土生土长的Go 主控程序 服务器 VyOS 路由器。编译为单个静态二进制文件，作为systemd服务直接在路由器上运行，并通过Streamable HTTP传输公开18个工具。

为什么

• 零运行时依赖关系 --一个静态二进制文件，没有PHP/Python/Node
• 不需要REST API --直接调用VyOS CLI工具，不需要API密钥或HTTPS配置
• 持久守护进程 --在路由器本身上运行，会话在客户端重新连接后仍然存在
• 生存升级 --二进制生活 /config/，在VyOS映像升级过程中持续存在
• 低延迟 --直接CLI执行，不涉及网络堆栈

建筑

Workstation                          VyOS Router
+-----------+    SSH tunnel          +-------------------------+
| MCP Client|---(port 8384)-------->| vyos-mcp-go daemon      |
| (Claude,  |  http://localhost:8384| listening 127.0.0.1:8384|
|  etc.)    |                       | Streamable HTTP on /mcp |
+-----------+                       |         |               |
                                    |         v               |
                                    |  VyOS CLI tools          |
                                    |  (vyatta-op-cmd-wrapper, |
                                    |   cli-shell-api, etc.)   |
                                    +-------------------------+

守护进程绑定到 127.0.0.1 只是——它不暴露在网络中。通过SSH隧道从工作站访问它。

安全

为什么只绑定localhost很重要

MCP服务器绑定到 127.0.0.1:8384 和 不得 暴露在网络接口上。这一点至关重要，因为：

• MCP协议没有身份验证。 任何可以到达HTTP端点的客户端都可以调用任何工具，包括 vyos_set_config, vyos_delete_config，以及 vyos_commit。这是对路由器配置的完全读/写访问权限，不需要凭据。
• 它在你的路由器上运行。 受损的路由器意味着受损的网络。防火墙规则、NAT、DNS、DHCP——所有这些都是通过这些工具控制的。
• 守护进程以root权限运行。 它需要访问需要root权限的VyOS配置会话工具。暴露MCP端点将授予未经身份验证的远程根级配置访问权限。

通过绑定到localhost，到达服务器的唯一方法是通过SSH隧道，该隧道提供MCP本身所缺乏的身份验证（SSH密钥）、加密和访问控制。

从不 将监听地址更改为 0.0.0.0 或LAN IP。如果需要远程访问，请始终使用SSH隧道。

其他措施

• SSH隧道继承了您现有的SSH密钥身份验证和加密
• systemd服务与一起运行 NoNewPrivileges=yes 和 PrivateTmp=yes
• 配置修改操作使用互斥体序列化，以防止竞争条件

先决条件

• VyOS 1.4+（在1.5滚动测试中）
• 使用sudo通过SSH访问路由器（建议基于密钥）
• 在您的构建机器上运行1.26+（或让 ensure-go.sh 自动下载）

注： 与REST API方法不同，此服务器 不 要求启用VyOS HTTPS API。它直接调用VyOS CLI工具。

快速开始

git clone https://github.com/rlerdorf/vyos-mcp-go.git
cd vyos-mcp-go

# Build (cross-compiles a static linux/amd64 binary)
make build

# Deploy to router
# Requires: SSH host "router" configured in ~/.ssh/config
make deploy

# Open an SSH tunnel (in a separate terminal or as a background service)
make tunnel

# Verify it works
make test

SSH配置

Makefile假定一个名为的SSH主机 router。将此添加到 ~/.ssh/config:

Host router
    HostName 192.168.1.1    # your router's LAN IP
    User vyos               # or your VyOS username
    IdentityFile ~/.ssh/id_ed25519

用以下命令覆盖Makefile中的主机名 ROUTER=your-host.

部署详情

部署什么

就是这样——没有配置文件，没有API键，没有环境变量。

幸存的重启

添加以下内容 /config/scripts/vyos-postconfig-bootup.script 在路由器上，这样每次启动后服务都会自动启动（包括VyOS升级）：

# MCP server
ln -sf /config/user-data/mcp-server.service /etc/systemd/system/mcp-server.service
systemctl daemon-reload
systemctl enable mcp-server
systemctl restart mcp-server

MCP客户端配置

克劳德代码

添加到您的项目 .mcp.json:

{
  "mcpServers": {
    "vyos": {
      "type": "http",
      "url": "http://localhost:8384/mcp"
    }
  }
}

需要一个活动的SSH隧道（见下文）。

其他MCP客户端

任何支持Streamable HTTP传输的客户端都可以连接到 http://localhost:8384/mcp （隧道处于活动状态）。

SSH 隧道

手册

ssh -L 8384:localhost:8384 -N router

持久（systemd用户服务）

创建 ~/.config/systemd/user/vyos-mcp-tunnel.service:

[Unit]
Description=SSH tunnel to VyOS MCP server

[Service]
ExecStart=/usr/bin/ssh -N -L 8384:localhost:8384 -o ServerAliveInterval=30 -o ServerAliveCountMax=3 router
Restart=on-failure
RestartSec=10

[Install]
WantedBy=default.target

然后：

systemctl --user daemon-reload
systemctl --user enable --now vyos-mcp-tunnel

工具

按类别组织的18种工具：

配置

可操作的

诊断

监控

构建系统

Makefile使用 ensure-go.sh 要自动管理Go工具链，请执行以下操作：

• 如果您的系统Go>=1.26，则使用该值
• 否则，它会将最新的Go从Go.dev下载到 .goroot/ （已缓存，SHA256已验证）

make build      # Cross-compile static binary
make deploy     # Build + deploy + restart
make tunnel     # SSH tunnel to router
make test       # Quick handshake test
make clean      # Remove binary
make clean-go   # Remove downloaded Go toolchain
make clean-all  # Both

覆盖默认值：

make deploy ROUTER=my-router DEPLOY_DIR=/config/scripts

项目结构

vyos-mcp-go/
  main.go              HTTP server, Streamable HTTP handler, graceful shutdown
  client.go            VyOS CLI client (calls vyatta-op-cmd-wrapper, cli-shell-api, etc.)
  tools.go             18 MCP tool registrations
  mcp-server.service   systemd unit file
  ensure-go.sh         Auto-downloads Go toolchain if needed
  Makefile             Build, deploy, tunnel, test targets
  go.mod / go.sum      Go module files

运作原理

VyOS CLI集成

服务器在启动时创建VyOS配置会话（通过 cli-shell-api getSessionEnv + setupSession)并直接使用VyOS CLI工具：

这与VyOSHTTP API服务器内部使用的方法相同——它使用这些确切的工具。通过直接调用它们，我们完全跳过了HTTPS/API-key/nginx层。

MCP传输

使用官方 Go MCP SDKs StreamableHTTPHandler 在一个单一 /mcp 终点。这是推荐的传输方式（取代了弃用的SSE传输方式），通过HTTP提供双向JSON-RPC，服务器发送事件用于流式响应。

许可证

麻省理工学院