VyMCP

Model Context Protocol (MCP) server for VyOS routers, powered by VyManager.

VyMCP lets AI agents and MCP-aware tools (Claude, IDEs, automation) read and manage VyOS routers through a safe, audited interface. Rather than talking to routers directly, VyMCP wraps the VyManager API — so every action inherits VyManager's per-user authentication, role-based access control, audit logging, and version-aware (VyOS 1.4 / 1.5) configuration handling.

Status: alpha. Read tools cover every VyManager feature; guarded write tools currently cover firewall address groups, with more features being added. The transport is stdio today (hosted HTTP/SSE is planned). Interfaces may still change.

Why a server, not a direct integration

VyMCP deliberately does not connect to VyOS devices itself. It is a thin, stateless translation layer in front of VyManager's REST API. This keeps a single, enforced source of truth for everything that matters in an enterprise environment:

• Per-user identity — a VyMCP request acts as a real VyManager user, never a shared service account.

• RBAC — a token can never exceed its owner's permissions.

• Audit — every configuration change is attributed to the user, token, and instance.

• Commit-confirm safety — writes ride VyManager's existing safety rails.

• Version awareness — VyOS 1.4 vs 1.5 differences are handled by VyManager, not reimplemented here.

  MCP client (Claude / IDE / agent)
        │   MCP over HTTP+SSE (or stdio)
        ▼
     VyMCP  ── stateless translation layer
        │   Authorization: Bearer vym_…
        │   X-VyOS-Instance-Id: <instance>
        ▼
   VyManager API ── RBAC · audit · commit-confirm · 1.4/1.5 mappers
        │
        ▼
    VyOS 1.4 / 1.5

Related MCP server: MikroMCP

Security model

VyMCP authenticates to VyManager with a personal access token that a user mints in the VyManager UI (Sites → API Tokens). Tokens are least-privilege by design:

• Read-only scope — a token can be restricted so it can never make configuration changes.

• Instance/site scoping — a token can be limited to specific routers or sites (always within the user's own grants).

• Per-call targeting — the target router is selected per request via the instance the token is allowed to reach.

This means you can hand VyMCP a token that, for example, can only read a single production router — and that limit is enforced by VyManager, not by VyMCP.

Tools

Read (always available):

Write (only when VYMANAGER_ENABLE_WRITES=true): changes go through a mandatory propose → apply flow — a propose_* tool validates and returns a plan_id without touching anything, then apply_change(plan_id, confirm=true) executes that one reviewed plan. Plans are single-use, time-limited, and bound to their target instance.

Guardrails

• Read-only by default — write tools are not even registered unless VYMANAGER_ENABLE_WRITES=true, on top of the token's own read-only scope (a read-only token is rejected by VyManager regardless).

• No arbitrary config — only curated, typed operations; there is no "set any path" tool.

• Propose → apply — apply_change requires confirm=true and a valid plan id, so the model can only apply a change a human has seen.

• Never auto-confirms — applied changes ride VyManager's commit-confirm timer and auto-revert unless explicitly confirmed.

Requirements

• A reachable VyManager instance.

• A VyManager API token (Sites → API Tokens; read-only recommended to start).

• One or more VyOS 1.4 / 1.5 routers registered in VyManager.

• Python 3.10+.

Getting started

Install:

pip install -e .          # or: pip install -e ".[dev]" for tests

Configure via environment variables (see .env.example):

export VYMANAGER_BASE_URL="https://vymanager.example.com"
export VYMANAGER_API_TOKEN="vym_…"      # read-only recommended
# export VYMANAGER_ENABLE_WRITES=true   # opt in to write tools

Register with an MCP client (stdio). Example client config:

{
  "mcpServers": {
    "vymcp": {
      "command": "vymcp",
      "env": {
        "VYMANAGER_BASE_URL": "https://vymanager.example.com",
        "VYMANAGER_API_TOKEN": "vym_…"
      }
    }
  }
}

Development

pip install -e ".[dev]"
pytest          # deterministic; no live device needed
ruff check .
mypy

Roadmap

• stdio server + token auth to VyManager

• Read tools across all features

• Guarded write tools (propose → apply → commit-confirm)

• More curated write features

• Hosted remote transport (HTTP/SSE) with per-user auth

• Packaging and deployment docs

Related projects

• VyManager — the web UI and API that VyMCP builds on.

License

See LICENSE for details.