Mcp Server Vyos

mcp-server-vyos

[](https://github.com/cacack/mcp-server-vyos/actions/workflows/ci.yml) [](https://codecov.io/gh/cacack/mcp-server-vyos) [](https://pypi.org/project/mcp-server-vyos/) [](https://pypi.org/project/mcp-server-vyos/) [](https://opensource.org/licenses/MIT)

MCP server for VyOS router management via the HTTPS REST API. Provides both router management tools and live VyOS documentation lookup.

Installation

pip install mcp-server-vyos

Configuration

Set environment variables:

• VYOS_URL — Router API endpoint (e.g., https://vyos.example.com)
• VYOS_API_KEY — API key for authentication
• VYOS_READ_ONLY — Set to true to disable all mutating tools (config changes, reboot, poweroff, etc.)

VyOS Router Setup

Enable the HTTPS API on your VyOS router:

configure
set service https api keys id my-mcp-key key 
set service https api rest
commit
save

Claude Code

Add to your MCP client configuration:

{
  "mcpServers": {
    "vyos": {
      "command": "mcp-server-vyos",
      "env": {
        "VYOS_URL": "https://vyos.example.com",
        "VYOS_API_KEY": "your-api-key"
      }
    }
  }
}

Read-Only Mode

For safe, query-only access (monitoring, investigation, documentation lookup), enable read-only mode:

{
  "mcpServers": {
    "vyos": {
      "command": "mcp-server-vyos",
      "env": {
        "VYOS_URL": "https://vyos.example.com",
        "VYOS_API_KEY": "your-api-key",
        "VYOS_READ_ONLY": "true"
      }
    }
  }
}

This registers only non-mutating tools: vyos_info, vyos_retrieve, vyos_return_values, vyos_exists, vyos_config_diff, vyos_config_history, vyos_show, vyos_traceroute, vyos_interface_stats, vyos_system_resources, vyos_route_table, vyos_firewall_stats, vyos_bgp_summary, vyos_docs_search, and vyos_docs_read.

Tools

Router Management

| Tool | Description | |---|---| | vyos_info | System info (no auth required) | | vyos_retrieve | Read configuration at a path | | vyos_return_values | Get multi-valued config node values | | vyos_exists | Check if a config path exists | | vyos_config_diff | Show config differences (saved vs running, or by revision) | | vyos_config_history | List config revision history (number, timestamp, user, method) | | vyos_show | Run operational show commands | | vyos_validate | Validate config syntax (temporary apply with auto-rollback) | | vyos_configure | Apply config with commit-confirm (safe default) | | vyos_confirm | Confirm a pending commit-confirm | | vyos_save | Save running config to disk | | vyos_load | Load a configuration file | | vyos_merge | Merge config file or string into running config | | vyos_generate | Generate keys, certificates, etc. | | vyos_reset | Reset operations | | vyos_reboot | Reboot the router | | vyos_poweroff | Power off the router | | vyos_image_add | Add a system image from URL | | vyos_image_delete | Delete a system image |

Diagnostics

| Tool | Description | |---|---| | vyos_traceroute | Traceroute to a host (structured mtr report) | | vyos_interface_stats | Interface RX/TX counters, errors, and link state | | vyos_system_resources | CPU, memory, storage, and uptime snapshot | | vyos_route_table | Routing table (RIB) by family/protocol (show ip route) | | vyos_firewall_stats | Firewall and NAT rule hit counters | | vyos_bgp_summary | BGP neighbor summary (state, prefixes received) |

Documentation

| Tool | Description | |---|---| | vyos_docs_search | Search VyOS docs by topic and page content (returns snippets) | | vyos_docs_read | Read a specific documentation page |

Documentation is fetched live from the vyos-documentation repository, so it stays in sync with the latest VyOS releases. Results are cached for 1 hour.

Safety

• Configuration changes use commit-confirm by default -- changes auto-revert after 5 minutes unless confirmed with vyos_confirm
• vyos_configure accepts a list of operations applied atomically in one commit-confirm -- batch related changes into a single call so they commit or roll back together
• Destructive operations (vyos_reboot, vyos_poweroff, vyos_image_delete) include warning descriptions
• API keys are never logged or included in tool outputs
• Self-signed TLS certificates are accepted by default (common on VyOS)

Development

uv venv && source .venv/bin/activate
uv pip install -e ".[dev]"
pytest
ruff check .

License

MIT

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: cacack
• Source: cacack/mcp-server-vyos
• License: MIT

Install and usage instructions live in the source repository linked above.