vyos-mcp
An MCP server for managing VyOS routers via the HTTPS REST API, enabling configuration changes, operational commands, and system maintenance tasks. It also provides tools to search and read live VyOS documentation directly from official sources to assist with command syntax and router features.
Ask AI about vyos-mcp
Powered by Claude Β· Grounded in docs
I know everything about vyos-mcp. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
mcp-server-vyos
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 authenticationVYOS_READ_ONLYβ Set totrueto 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 <your-api-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_show, 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_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 |
Documentation
| Tool | Description |
|---|---|
vyos_docs_search | Search VyOS documentation by topic |
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-confirmby default -- changes auto-revert after 5 minutes unless confirmed withvyos_confirm - 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
