Metadata-Version: 2.4
Name: vyos-mcp
Version: 0.1.0
Summary: MCP server for managing VyOS routers via the VyOS HTTP API
Project-URL: Homepage, https://github.com/alch3mistdev/vyos-mcp
Project-URL: Repository, https://github.com/alch3mistdev/vyos-mcp
Project-URL: Issues, https://github.com/alch3mistdev/vyos-mcp/issues
Author: Anthony Nixon
License-Expression: MIT
License-File: LICENSE
Keywords: mcp,model-context-protocol,networking,router,vyos
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: System :: Networking
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp[cli]>=1.0.0
Requires-Dist: pydantic>=2.0.0
Description-Content-Type: text/markdown

# VyOS MCP Server

An [MCP](https://modelcontextprotocol.io) 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.

## Prerequisites

A VyOS router (1.4+ or rolling) with the HTTP API enabled:

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

## Quick Start

No installation needed — run directly with [`uvx`](https://docs.astral.sh/uv/guides/tools/):

```bash
uvx vyos-mcp
```

### Claude Code

```bash
claude mcp add vyos \
  -e VYOS_URL=https://10.0.0.1 \
  -e VYOS_API_KEY=YOUR_API_KEY \
  -e VYOS_VERIFY_SSL=false \
  -- uvx vyos-mcp
```

Or add to your `~/.claude.json` or project `.mcp.json`:

```json
{
  "mcpServers": {
    "vyos": {
      "command": "uvx",
      "args": ["vyos-mcp"],
      "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:

- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "vyos": {
      "command": "uvx",
      "args": ["vyos-mcp"],
      "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, 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"

## Development

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

## License

MIT
