vyos-mcp

vyos-mcp

An MCP server for managing VyOS appliances over their HTTP API. It exposes tools for the config verbs (show / set / delete), the config lifecycle (commit-confirm / revert / save), operational show commands and log retrieval/search, plus two guided "skill" prompts for traffic analysis and interactive troubleshooting.

Transport is streamable HTTP only.

How it works

VyOS exposes a REST API where every call is a POST of a multipart form with a data JSON op descriptor and a per-appliance key. This server wraps that API behind well-described MCP tools, selecting the target appliance by name from a YAML inventory.

API reference: <https://docs.vyos.io/en/latest/automation/vyos-api.html>

Commit model (important)

VyOS's /configure endpoint commits immediately — there is no separate commit step. To get a safe, revertible edit:

1. set_config / delete_config with confirm_minutes > 0 — applies a commit-confirm; the

change auto-reverts after that many minutes unless confirmed.

1. Verify with show_config / run_show.
2. confirm_commit — keep the change.
3. save_config — persist to boot config.

revert_config reloads the last saved config (/config/config.boot), discarding unsaved running changes.

Tools

| Tool | Purpose | |---|---| | list_appliances | List managed appliances (no keys) | | show_config | Read config (showConfig / exists / returnValue / returnValues) | | list_options | List the configured child nodes under a path (explore the tree to build set/delete paths) | | set_config | Apply set commands (single or batch), optional commit-confirm | | delete_config | Apply delete commands (single or batch), optional commit-confirm | | confirm_commit | Finalize a pending commit-confirm | | revert_config | Reload the last saved config | | save_config | Persist running config to boot | | run_show | Run an operational show command | | get_logs | Retrieve / regex-search system logs with tail | | command_help | Look up the bundled VyOS command schema at a path (help, value formats, allowed values, constraints, child options) | | search_commands | Search the bundled command schema by keyword to find where a feature lives |

Command schema (offline "help" for the model)

The VyOS HTTP API has no command-completion endpoint, so list_options can only show what is currently configured. To give the model the full command tree — what can be set or run, with help text, value formats, allowed values and constraints — this server bundles a compiled schema generated from VyOS's own XML interface/op-mode definitions.

• command_help — at a path, returns the node's help plus its child options (config tree via

mode: configure, or the show/operational tree via mode: operational). This is how the model discovers the exact tokens for a set_config / run_show call.

• search_commands — keyword search across the tree ("where does NAT live?").

Bundled versions (last 3 stable releases) live in data/ and are selected per appliance via the optional version field (1.3, 1.4, 1.5; defaults to newest). Both tools also accept an explicit version.

Regenerate the bundled schemas (e.g. when a new VyOS release ships) with:

npm run build:schema   # downloads the pinned branches and rewrites data/vyos-*.json

Edit the VERSIONS list in scripts/build-schema.mjs to change which releases are bundled.

The schema is a pinned snapshot. If an appliance runs a version not bundled, set its version to the closest bundled one; dynamic completions (values generated on the box) are shown as hints rather than concrete value lists.

Prompts (skills)

• traffic_analysis(appliance, interface?, focus?)
• troubleshoot(appliance, symptom) — interactive; asks you to run tests and correlates results.

Setup

npm install
npm run build

Enable the API on each VyOS appliance

set service https api keys id mcp key '<PLAINTEXT-KEY>'
set service https api
commit ; save

Configure the inventory

Copy the example and edit it:

cp appliances.example.yaml appliances.yaml

appliances:
  - name: edge-fw
    host: 10.0.0.1
    port: 443            # default 443
    verify_ssl: false    # default true; opt out per appliance for self-signed certs
    api_key: ${EDGE_FW_KEY}   # literal, or ${ENV_VAR} reference
    description: "Branch edge firewall"

API keys may be ${ENV_VAR} references so secrets stay out of the file. Referenced vars must be set when the server starts. The config path defaults to ./appliances.yaml; override with VYOS_MCP_CONFIG.

TLS: verify_ssl defaults to true (secure by default). Because VyOS ships a self-signed certificate, verification will fail until you install a properly-issued certificate or add the appliance CA to the host trust store. You can set verify_ssl: false per appliance to skip verification, but that exposes the connection to man-in-the-middle attacks — only do so on a trusted network.

Run

export EDGE_FW_KEY=...     # any env vars referenced by appliances.yaml
npm start                  # or: npm run dev

Server listens on http://localhost:3000/mcp (PORT, VYOS_MCP_PATH configurable). Health check at GET /health.

The MCP endpoint itself is unauthenticated. Bind it to localhost or a trusted network, or front it with a reverse proxy that adds auth.

Connect from Claude Code

claude mcp add --transport http vyos http://localhost:3000/mcp

Smoke test with the MCP Inspector

# List tools
npx @modelcontextprotocol/inspector --cli http://localhost:3000/mcp \
  --transport http --method tools/list

# List appliances
npx @modelcontextprotocol/inspector --cli http://localhost:3000/mcp \
  --transport http --method tools/call --tool-name list_appliances

# Read config
npx @modelcontextprotocol/inspector --cli http://localhost:3000/mcp \
  --transport http --method tools/call --tool-name show_config \
  --tool-arg appliance=edge-fw --tool-arg 'path=["interfaces"]'

# List prompts
npx @modelcontextprotocol/inspector --cli http://localhost:3000/mcp \
  --transport http --method prompts/list

Not included

The VyOS /generate, /reset, /renew, /reboot, /poweroff, /image and /traceroute endpoints are not wrapped yet — they follow the same pattern in src/tools.ts if you need them.