Asuswrt Mcp Server

AsusWRT MCP サーバー

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

SSH 経由で AsusWRT および AsusWRT-Merlin ルーターを安全かつ制御された方法で管理するための Model Context Protocol（MCP）サーバーです。

概要

この MCP サーバーは、AI アシスタント（Claude、Cursor など）に、AsusWRT ルーターを監視・管理するための安全なインターフェースを提供します。許可リストに登録された操作のみを使用して SSH 経由で動作し、任意のコマンド実行、ファームウェアの変更、工場出荷時設定へのリセットは行いません。

機能

読み取り専用の監視（42 個のツール）

カテゴリ	ツール
識別情報と稼働状況	ルーターモデル、ファームウェアバージョン、稼働時間、負荷、メモリ
ネットワーク	LAN/WAN の詳細、DNS 設定、IPv6 の状態、ルーティングテーブル
クライアント	接続中のクライアント、DHCP リース、ARP ネイバー
ワイヤレス	無線の状態、SSID、ゲストネットワーク、帯域ごとのクライアント数
サービス	実行中のプロセス、開いているポート、cron ジョブ
ストレージ	USB デバイス、マウント、パーティション、ファイルシステムの使用状況
セキュリティ	UPnP、DDNS、Samba の状態、conntrack の使用状況
VPN	OpenVPN サーバー、WireGuard、VPN クライアントプロファイル
管理	Web 管理ポート、SSH/telnet アクセス設定
診断	SSH の TCP／バナー／認証診断、設定スナップショット

変更ツール（安全ガード付き）

すべての変更ツールには、次の条件が必要です。

• confirm: true パラメーター
• ASUSWRT_ALLOW_MUTATIONS=true 環境変数
• 変更をプレビューする dry_run: true のサポート

ツール	説明
asuswrt_restart_service	許可リストに登録されたサービス（httpd、firewall、wireless、dnsmasq など）を再起動します
asuswrt_dhcp_server	DHCP サーバーを有効化／無効化します
asuswrt_upnp	UPnP を有効化／無効化します
asuswrt_radio	Wi-Fi 無線帯域を有効化／無効化します
asuswrt_guest_wifi	ゲスト Wi-Fi を有効化／無効化します
asuswrt_guest_lan_access	ゲスト Wi-Fi の LAN アクセスを切り替えます
asuswrt_port_forwarding	ポートフォワーディングルールの一覧表示、追加、削除、有効化／無効化を行います
asuswrt_vpn_server	OpenVPN サーバーを有効化／無効化します
asuswrt_parental_access	ペアレンタルコントロールルールの一覧表示、ブロック、ブロック解除、削除を行います
asuswrt_parental_block_all	すべてブロックするモードを切り替えます
asuswrt_dhcp_reservation	DHCP 固定割り当ての一覧表示、追加、削除を行います

安全性モデル

• 任意の SSH コマンドは禁止：NVRAM およびサービス呼び出しを介して、許可リストに登録されたコマンドのみを実行します
• ファームウェア操作なし：フラッシュ、リセット、ブートローダーへのアクセスは行いません
• シークレットのマスキング：パスワードや機密データがツールの応答に表示されることはありません
• ドライランのサポート：すべての変更を適用前にプレビューできます
• 確認が必須：変更には明示的な confirm=True が必要です
• SSH のみで接続：ルーターの Web API は公開しません

前提条件

• Python 3.11+
• SSH アクセスが有効な AsusWRT または AsusWRT-Merlin ルーター
• MCP クライアントからルーターへのネットワーク接続

インストール

1. クローンしてセットアップ

git clone https://github.com/Teeflo/asuswrt-mcp.git
cd asuswrt-mcp

# Create virtual environment
python -m venv .venv

# Activate (Linux/macOS)
source .venv/bin/activate

# Activate (Windows)
.venv\Scripts\activate

# Install dependencies
pip install -e .

2. 環境を設定

# Copy example configuration
cp .env.example .env

# Edit with your router credentials
# Use your favorite editor:
notepad .env        # Windows
nano .env           # Linux/macOS

3. .env を設定

# Required: Router connection
ASUSWRT_HOST=192.168.1.1
ASUSWRT_SSH_USERNAME=admin
ASUSWRT_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

使用方法

MCP サーバーを実行

# Standard stdio mode
python -m asuswrt_mcp.server

# Or use the entry point
asuswrt-mcp

Claude Desktop / Cursor で設定

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"
      }
    }
  }
}

npx Inspector を使用する（開発用）

npx @modelcontextprotocol/inspector python -m asuswrt_mcp.server

開発

テストを実行

pip install -e ".[dev]"
pytest

ルーターとのライブ統合テストを実行

ASUSWRT_TEST_ROUTER=1 pytest

プロジェクト構成

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

ライセンス

MIT License。詳細は LICENSE を参照してください。

謝辞

• 基盤となる Python ライブラリを提供する asusrouter
• プロトコル仕様を提供する MCP
• ファームウェアを提供する AsusWRT-Merlin