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 ```bash 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: ```bash configure set service https api keys id my-mcp-key key <your-api-key> set service https api rest commit save ``` ### Claude Code Add to your MCP client configuration: ```json { "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: ```json { "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](https://github.com/vyos/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 ```bash uv venv && source .venv/bin/activate uv pip install -e ".[dev]" pytest ruff check . ``` ## License MIT