# VyOS MCP Server

An MCP (Model Context Protocol) server for managing VyOS routers via the VyOS HTTP API. Gives any MCP-compatible AI assistant full control over your VyOS router — from reading config to setting up interfaces, firewall rules, VPNs, and more.

## Requirements

- Python 3.10+
- A VyOS router (1.4+ or rolling) with the HTTP API enabled

### Enable the VyOS HTTP API

On your VyOS router:

```bash
configure
set service https api keys id my-app key 'YOUR_API_KEY'
set service https api rest
commit
save
```

## Installation

```bash
git clone https://github.com/openclaw/vyos-mcp.git
cd vyos-mcp
python -m venv .venv
source .venv/bin/activate
pip install -e .
```

## Configuration

### Claude Code

Add to your `~/.claude.json` (or project `.mcp.json`):

```json
{
  "mcpServers": {
    "vyos": {
      "command": "/path/to/vyos-mcp/.venv/bin/python",
      "args": ["-m", "vyos_mcp.server"],
      "env": {
        "VYOS_URL": "https://10.0.0.1",
        "VYOS_API_KEY": "YOUR_API_KEY",
        "VYOS_VERIFY_SSL": "false"
      }
    }
  }
}
```

### Claude Desktop

Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "vyos": {
      "command": "/path/to/vyos-mcp/.venv/bin/python",
      "args": ["-m", "vyos_mcp.server"],
      "env": {
        "VYOS_URL": "https://10.0.0.1",
        "VYOS_API_KEY": "YOUR_API_KEY",
        "VYOS_VERIFY_SSL": "false"
      }
    }
  }
}
```

### Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `VYOS_URL` | Yes | Base URL of your VyOS router (e.g. `https://10.0.0.1`) |
| `VYOS_API_KEY` | Yes | API key configured on the router |
| `VYOS_VERIFY_SSL` | No | Set to `false` to skip TLS verification (default: `true`) |

## Tools

### Read-Only

| Tool | Description |
|------|-------------|
| `vyos_info` | Get system version, hostname, and banner (no auth required) |
| `vyos_show` | Run operational-mode `show` commands (interfaces, routes, BGP, etc.) |
| `vyos_show_config` | Retrieve running configuration (full or partial subtree) |
| `vyos_exists` | Check whether a configuration path exists |
| `vyos_return_values` | Return values of a multi-valued config node (e.g. DNS servers) |

### Configuration

| Tool | Description |
|------|-------------|
| `vyos_set` | Set a single configuration path |
| `vyos_delete` | Delete a configuration path and its children |
| `vyos_comment` | Add a comment to a configuration node |
| `vyos_configure_batch` | Apply multiple set/delete/comment operations in a single atomic commit |

All configuration tools automatically save to `/config/config.boot` after a successful commit, so changes persist across reboots.

Use `confirm_time` (1-60 minutes) on any config tool for safe rollback — changes auto-revert unless confirmed with `vyos_confirm_commit`.

### Config File Management

| Tool | Description |
|------|-------------|
| `vyos_save_config` | Save running config to disk (default or custom path) |
| `vyos_load_config` | Load a config file, replacing the running configuration |
| `vyos_merge_config` | Merge config from a file or inline string into running config |
| `vyos_confirm_commit` | Confirm a pending commit-confirm timer |

### System

| Tool | Description |
|------|-------------|
| `vyos_generate` | Run generate commands (WireGuard keys, certificates, etc.) |
| `vyos_reset` | Reset protocol sessions, counters, or runtime state |
| `vyos_image` | Add (download) or delete system images |
| `vyos_system_control` | Reboot or power off the router (requires explicit confirmation) |

## Examples

Once configured, you can ask your AI assistant things like:

- "Show me the current interface status"
- "Set up eth0 as WAN with DHCP and eth1 as LAN with a DHCP server on 192.168.1.0/24"
- "Add a firewall rule to block incoming traffic on port 22 from WAN"
- "Set up a WireGuard VPN tunnel to 203.0.113.1"
- "Show me the routing table"
- "What DHCP leases are active?"
- "Generate a new WireGuard key pair"

## License

MIT