sonic-net-debugger

An MCP (Model Context Protocol) server for debugging and interacting with SONiC (Software for Open Networking in the Cloud) network devices (DUTs).

Features

• CLI Command Execution: Execute SONiC utility commands (like show pfc wd stats, show interfaces status, etc.) directly on the device via SSH.

• Redis Querying: Access the SONiC Redis databases (APPL_DB, ASIC_DB, STATE_DB, etc.) to inspect internal switch states.

• Documentation Retrieval: Built-in access to the SONiC Command Reference, allowing AI to lookup exact syntaxes for complex commands. The server will automatically download the documentation from the official GitHub repository on its first run.

• Dynamic Device Targeting & Smart Authentication:

  • Supports passing target IP, username, and password dynamically per request.

  • Auto-Fallback Credential Testing: If no credentials are provided during the request, the server will automatically cycle through a list of default lab passwords (loaded from config.json) using a Cartesian product (matching every username with every password) until it successfully connects.

  • Smart Credential Caching: Successfully authenticated IP, Username, and Password combinations are temporarily cached locally (.ssh_cache.json). Subsequent commands to the same device will instantly use the cached credentials, bypassing the credential permutations to significantly speed up execution.

Related MCP server: debugpy-mcp

Requirements

• Python 3.10+

• fastmcp

• paramiko

Installation

pip install -r requirements.txt

Configuration

This MCP server communicates over standard input/output (stdio) and uses SSH to connect to the SONiC switch.

1. Environment Variables (Primary Device)

You can provide default environment variables. These will be attempted first before falling back to common default passwords.

• SONIC_HOST: The default IP address or hostname of the switch (e.g., 10.110.199.18).

• SONIC_USER: Your specific SSH username.

• SONIC_PASS: Your specific SSH password.

2. Credential Permutations (config.json)

To avoid hardcoding lab passwords into the script, the tool will automatically generate a config.json file in its root directory upon first execution. You can populate this file with common usernames and passwords used in your network lab:

{
    "usernames": [
        "admin",
        "root"
    ],
    "passwords": [
        "YourPassword",
        "admin",
        "password",
        "123456",
        "root"
    ]
}

Note: config.json, .ssh_cache.json and downloaded .md files are added to .gitignore to prevent accidental credential leaks.

Example configuration for Claude Desktop or Cursor:

{
  "mcpServers": {
    "sonic-net-debugger": {
      "command": "python",
      "args": ["/path/to/sonic-net-debugger/sonic_net_debugger.py"],
      "env": {
        "SONIC_HOST": "10.110.199.18"
      }
    }
  }
}

Available Tools

• sonic_exec_cmd(command, host, username, password): Execute a CLI command on the device via SSH.

• sonic_lookup_doc(keyword): Search the local SONiC command reference markdown file.

• sonic_query_redis(db_index, pattern, host, username, password): Query Redis keys using redis-cli KEYS.

• sonic_get_redis_hash(db_index, key, host, username, password): Get all fields and values of a specific Redis HASH key.

(Note: host, username, and password are optional parameters. If omitted, the server handles connection and authentication automatically using environment variables, cache, and config.json.)