Asuswrt Mcp

AsusWRT MCP Server

[Python 3.11+] [MIT License] [Project Status: Active]

mcp-name: io.github.teefloo/asuswrt-mcp

Model Context Protocol (MCP) server for secure, controlled administration of AsusWRT and AsusWRT-Merlin routers via SSH.

Overview

This MCP server provides AI assistants (like Claude, Cursor, etc.) with a safe interface to monitor and manage AsusWRT routers. It operates exclusively over SSH using allowlisted operations—no arbitrary command execution, no firmware modifications, and no factory resets.

Features

Read-Only Monitoring (42 tools)

Mutation Tools (with safety guards)

All mutation tools require:

• confirm: true parameter
• ASUSWRT_ALLOW_MUTATIONS=true environment variable
• Support for dry_run: true to preview changes

Safety Model

• No arbitrary SSH: Only allowlisted commands are executed via NVRAM and service calls
• No firmware operations: No flash, reset, or bootloader access
• Secret redaction: Passwords and sensitive data are never exposed in tool responses
• Dry-run support: Every mutation can be previewed before applying
• Confirmation required: Mutations require explicit confirm=True
• SSH-only transport: No exposure of the router's web API

Prerequisites

• Python 3.11+
• An AsusWRT or AsusWRT-Merlin router with SSH access enabled
• Network connectivity from the MCP client to the router

Installation

1. Clone and setup

git clone https://github.com/Teeflo/asuswrt-mcp.gitcd asuswrt-mcp
# Create virtual environmentpython -m venv .venv
# Activate (Linux/macOS)source .venv/bin/activate
# Activate (Windows).venv\Scripts\activate
# Install dependenciespip install -e .

2. Configure environment

# Copy example configurationcp .env.example .env
# Edit with your router credentials# Use your favorite editor:notepad .env        # Windowsnano .env           # Linux/macOS

3. Configure .env

# Required: Router connectionASUSWRT_HOST=192.168.1.1ASUSWRT_SSH_USERNAME=adminASUSWRT_SSH_PASSWORD=your_password
# Optional: SSH key authentication# ASUSWRT_SSH_KEY_FILE=~/.ssh/id_rsa
# Optional: Enable mutations (disabled by default)# ASUSWRT_ALLOW_MUTATIONS=true
# Optional: Connection settings# ASUSWRT_SSH_PORT=22# ASUSWRT_TIMEOUT_SECONDS=10

Usage

Run the MCP server

# Standard stdio modepython -m asuswrt_mcp.server
# Or use the entry pointasuswrt-mcp

Configure in Claude Desktop / Cursor

Add to your claude_desktop_config.json:

{  "mcpServers": {    "asuswrt-mcp": {      "command": "C:\\path\\to\\asuswrt-mcp\\.venv\\Scripts\\python.exe",      "args": ["-m", "asuswrt_mcp.server"],      "env": {        "ASUSWRT_HOST": "192.168.1.1",        "ASUSWRT_SSH_USERNAME": "admin",        "ASUSWRT_SSH_PASSWORD": "your_password"      }    }  }}

Using with npx Inspector (development)

npx @modelcontextprotocol/inspector python -m asuswrt_mcp.server

Development

Run tests

pip install -e ".[dev]"pytest

Run with live router integration tests

ASUSWRT_TEST_ROUTER=1 pytest

Project Structure

asuswrt-mcp/├── src/asuswrt_mcp/│   ├── server.py          # FastMCP entrypoint & tool definitions│   ├── service.py         # Business logic & router operations│   ├── config.py          # Settings management│   ├── clients/│   │   └── ssh.py         # SSH client wrapper│   ├── nvram.py           # NVRAM parsing utilities│   ├── ssh_parsers.py     # Output parsers for SSH commands│   ├── security.py        # Mutation guards & redaction│   ├── validators.py      # Input validation│   ├── responses.py       # Tool response formatting│   ├── errors.py          # Custom exceptions│   └── serialization.py   # Safe serialization├── tests/                 # Test suite (69 tests)├── .env.example           # Example configuration├── pyproject.toml         # Project metadata└── README.md              # This file

License

MIT License - see LICENSE for details.

Acknowledgments

• asusrouter for the underlying Python library
• MCP for the protocol specification
• AsusWRT-Merlin for the firmware