VyOS MCP Server

A comprehensive Model Context Provider (MCP) server for VyOS network operating system automation. This server provides complete access to VyOS functionality through 25+ tools covering configuration management, operational commands, system administration, network diagnostics, and monitoring.

🚀 Features

• Complete VyOS API Coverage: All endpoints from VyOS HTTPS API
• Type Safety: Full TypeScript with Zod schema validation
• MCP Compatible: Works with Claude Desktop and other MCP clients
• Streaming Support: SSE transport for real-time communication
• OpenAPI v3.1: Auto-generated API documentation
• Error Handling: Robust error management with proper HTTP status codes

📋 Requirements

• Bun v1.0+ (JavaScript runtime and package manager)
• TypeScript v5.6+ with strict configuration
• VyOS system with HTTPS API enabled
• MCP Client (Claude Desktop, etc.)

🛠️ Installation

From JSR (Recommended)

# Install from JSR
bunx jsr add @danielbodnar/vyos-mcp

# Or with other package managers
npx jsr add @danielbodnar/vyos-mcp
pnpm dlx jsr add @danielbodnar/vyos-mcp
yarn dlx jsr add @danielbodnar/vyos-mcp

From Source

# Clone or navigate to project directory
cd vyos-mcp

# Install dependencies
bun install

# Generate OpenAPI specification
bun run openapi

# Generate documentation
bun run docs

# Start development server
bun run dev

Using as a Library (JSR)

import { VyOSClient } from "@danielbodnar/vyos-mcp";

// Create client instance
const client = new VyOSClient({
  host: "https://vyos.example.com",
  apiKey: "your-api-key",
  timeout: 30000,
  verifySSL: false
});

// Configure interface
await client.setConfig(["interfaces", "ethernet", "eth0", "address"], "192.168.1.1/24");
await client.commit("Configure LAN interface");
await client.save();

🔧 Configuration

VyOS System Setup

Enable the HTTPS API on your VyOS system:

# Enter configuration mode
configure

# Enable HTTPS API
set service https api keys id my-api-key key 'your-secure-api-key-here'

# Configure HTTPS certificates (optional, for production)
set service https certificates system-generated-certificate

# Commit and save
commit
save
exit

MCP Client Configuration

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

{
  "mcpServers": {
    "vyos": {
      "command": "bun",
      "args": ["run", "/path/to/vyos-mcp/src/index.ts"],
      "env": {}
    }
  }
}

🎯 Usage

1. Connect to VyOS System

// Use the vyos-connect tool
const connection = await vyosConnect({
  host: "https://192.168.1.1",
  apiKey: "your-api-key",
  timeout: 30000,
  verifySSL: false  // For self-signed certificates
});

2. Configuration Management

// Show configuration
await vyosShowConfig({
  path: ["interfaces", "ethernet"],
  format: "json"
});

// Set configuration values
await vyosSetConfig({
  path: ["interfaces", "ethernet", "eth0", "address"],
  value: "192.168.1.1/24",
  comment: "LAN interface configuration"
});

// Commit changes
await vyosCommit({
  comment: "Updated interface configuration",
  confirmTimeout: 10  // Auto-rollback in 10 minutes if not confirmed
});

// Save to startup config
await vyosSaveConfig();

3. Network Diagnostics

// Ping connectivity test
await vyosPing({
  host: "8.8.8.8",
  count: 5,
  timeout: 3
});

// Traceroute analysis
await vyosTraceroute({
  host: "google.com",
  maxHops: 30
});

4. System Monitoring

// Comprehensive health check
await vyosHealthCheck({
  includeInterfaces: true,
  includeRouting: true,
  includeServices: true,
  includeResources: true
});

// Interface statistics
await vyosInterfaceStats();

// BGP status
await vyosBgpStatus();

🔍 Available Tools

Authentication

• vyos-connect - Connect to VyOS system

Configuration Management

• vyos-show-config - Retrieve configuration
• vyos-set-config - Set configuration values
• vyos-delete-config - Delete configuration nodes
• vyos-config-exists - Check configuration existence
• vyos-return-values - Get configuration values
• vyos-commit - Commit pending changes
• vyos-save-config - Save to startup config

Operational Commands

• vyos-show-operational - Execute show commands
• vyos-reset - Execute reset commands
• vyos-generate - Execute generate commands

System Management

• vyos-system-info - Get system information
• vyos-reboot - Reboot system
• vyos-poweroff - Power off system
• vyos-health-check - Comprehensive health assessment

Network Interface Management

• vyos-configure-interface - Configure interface settings
• vyos-interface-stats - Get interface statistics

Routing

• vyos-configure-static-route - Configure static routes
• vyos-routing-table - Display routing table
• vyos-bgp-status - Get BGP status

Network Diagnostic Tools

• vyos-ping - Ping connectivity test
• vyos-traceroute - Traceroute network analysis

📖 Documentation

• API Documentation - Complete TypeDoc-generated documentation
• OpenAPI Specification - REST API specification
• VyOS Official Docs - VyOS documentation

Scripts

# Development
bun run dev              # Start with hot reloading
bun run build           # Build for production  
bun run start           # Start production server

# Documentation (Pure Bun/TypeScript)
bun run docs            # Generate TypeDoc documentation
bun run docs:serve      # Generate and serve docs on :8080
bun run docs:dev        # Serve existing docs (no rebuild)
bun run docs:watch      # Watch source files and rebuild docs
bun run docs:open       # Generate, serve, and open in browser
bun run docs:clean      # Clean generated documentation
bun run openapi         # Generate OpenAPI specification

# Quality
bun run typecheck       # TypeScript type checking
bun run lint           # ESLint code quality

🏗️ Architecture

Type Safety

• Zod Schemas: All API operations use Zod for runtime validation
• TypeScript: Strict typing throughout the codebase
• Generated Types: Type definitions derived from schemas

Error Handling

• HTTP Status Codes: Proper 200/400/500 responses
• VyOS API Errors: Translated to meaningful messages
• Network Timeouts: Configurable timeout handling
• Connection Management: Automatic retry and reconnection

Streaming

• SSE Transport: Server-Sent Events for real-time communication
• Bridge Pattern: Connects MCP server to transport layer
• CORS Support: Cross-origin requests for web clients

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Add comprehensive JSDoc documentation
4. Include TypeScript type definitions
5. Add error handling and validation
6. Update tests and documentation
7. Submit a pull request

📄 License

MIT License - see LICENSE file for details.

🆘 Support

• Issues: GitHub Issues
• VyOS Documentation: docs.vyos.io
• MCP Specification: Model Context Protocol

---

Built with ❤️ for network automation and infrastructure management.