Cisco NX-OS CLI MCP Server

A Model Context Protocol (MCP) server that lets you interact with Cisco NX-OS devices. You can send arbitrary CLI commands to one or more switches via their NX-API interface. This server exposes MCP tools for executing commands on one or more devices with comprehensive error handling. The output format can also be selected (text or JSON).

Features

• Single Device Commands: Execute CLI commands on individual NX-OS switches
• Multi-Device Commands: Execute the same commands across multiple switches concurrently
• Text-Based I/O: Commands are sent as text (cli_show_ascii), responses default to text format
• JSON Option: Optional JSON response format for structured parsing
• Simple Authentication: Credentials collected from .env file or on a per-request override
• Error Handling: Clear, actionable error messages
• Batch Operations: Execute up to 100 commands per request
• Concurrent Execution: Parallel command execution on multiple devices (up to 50)

Requirements

• Python 3.10 or higher
• Cisco NX-OS devices with NX-API enabled (feature nxapi)
• Network connectivity between the MCP host (Claude Desktop, etc.) to target devices via HTTPS

Installation

Prerequisites

• Python 3.10 or higher
• uv - Fast Python package installer (recommended)
• Cisco NX-OS devices with NX-API enabled (feature nxapi)
• Network connectivity to target devices via HTTPS

Setup

1. Install uv (if not already installed):

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

2. Install dependencies using uv:

# With uv and pyproject.toml (recommended)
uv sync

3. Set up authentication credentials:

Create a .env file from the template:

cp .env.example .env

Edit .env and add your credentials:

NXOS_USERNAME=admin
NXOS_PASSWORD=your_secure_password

Important: Never commit your production .env file to version control. .gitignore is configured to prevent this but be cautious!

Registering with MCP Hosts

Claude Desktop

macOS:

Edit the Claude Desktop configuration file:

code ~/Library/Application\ Support/Claude/claude_desktop_config.json

Add the NX-OS CLI MCP server to the mcpServers section:

{
  "mcpServers": {
    "nxos-cli": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/nxos-cli-mcp",
        "run",
        "nxos_cli_mcp.py"
      ]
    }
  }
}

Windows:

Edit the Claude Desktop configuration file:

notepad %APPDATA%\Claude\claude_desktop_config.json

Add the NX-OS CLI MCP server to the mcpServers section:

{
  "mcpServers": {
    "nxos-cli": {
      "command": "uv",
      "args": [
        "--directory",
        "C:\\absolute\\path\\to\\nxos-cli-mcp",
        "run",
        "nxos_cli_mcp.py"
      ]
    }
  }
}

After saving, restart Claude Desktop for the changes to take effect.

Visual Studio Code

macOS:

Edit the VS Code MCP settings file:

code ~/Library/Application\ Support/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/cline_mcp_settings.json

Add the server configuration:

{
  "mcpServers": {
    "nxos-cli": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/nxos-cli-mcp",
        "run",
        "nxos_cli_mcp.py"
      ]
    }
  }
}

Windows:

Edit the VS Code MCP settings file:

notepad %APPDATA%\Code\User\globalStorage\rooveterinaryinc.roo-cline\settings\cline_mcp_settings.json

Add the server configuration:

{
  "mcpServers": {
    "nxos-cli": {
      "command": "uv",
      "args": [
        "--directory",
        "C:\\absolute\\path\\to\\nxos-cli-mcp",
        "run",
        "nxos_cli_mcp.py"
      ]
    }
  }
}

After saving, reload the VS Code window (Command/Ctrl + Shift + P → "Developer: Reload Window").

Important Notes:

• Replace /absolute/path/to/nxos-cli-mcp (or C:\absolute\path\to\nxos-cli-mcp) with the actual full path to your project directory
• Ensure the .env file with your credentials is in the project directory
• The server will automatically load credentials from the .env file when started by the MCP client

Available Tools

1. nxos_execute_commands

Execute CLI commands on a single NX-OS device.

Parameters:

• ip_address (required): IP address or hostname of the device
• commands (required): List of CLI commands to execute
• response_format (optional): "text" (default, human-readable) or "json" (structured data)
• username (optional): Username for authentication
• password (optional): Password for authentication
• timeout (optional): Request timeout in seconds (default: 30)

2. nxos_execute_commands_multi

Execute the same CLI commands on multiple NX-OS devices concurrently.

Parameters:

• ip_addresses (required): List of device IP addresses or hostnames (max 50)
• commands (required): List of CLI commands to execute on all devices
• response_format (optional): "text" (default, human-readable) or "json" (structured data)
• username (optional): Username for authentication
• password (optional): Password for authentication
• timeout (optional): Request timeout in seconds per device (default: 30)
• continue_on_error (optional): Continue executing on other devices if one fails (default: true)

NX-API Configuration

Before using this MCP server, ensure NX-API is enabled on your NX-OS devices:

configure terminal
feature nxapi
nxapi http port 80
nxapi https port 443

Verify NX-API is running:

show nxapi

Security Considerations

1. Credentials: Store credentials in the .env file, never commit the file to version control
2. File Permissions: Ensure .env has restricted permissions (chmod 600 .env on Unix systems)
3. HTTPS: This MCP server talks HTTPS to NX-API (with verification disabled for self-signed certificates; change this for production!)

Output Formats

How Commands Are Sent

All commands are sent to NX-OS devices as text using the cli_show_ascii API type. This ensures consistent behavior with the CLI experience you're familiar with.

Response Formats

• text (default): Plain text output, identical to what you see in a CLI session

  • Easy to read in Claude Desktop or VS Code
  • Preserves formatting from the device
  • Best for interactive use

• json: Structured JSON response with detailed metadata, possibly better for MCP Hosts (experiment)

  • Includes success/failure status per device
  • Command execution results
  • Error details when applicable
  • Useful for programmatic parsing or complex workflows

Error Handling

The server provides detailed error messages for common scenarios:

• Authentication Failures: "Authentication failed. Check username and password."
• Permission Denied: "Permission denied. User may not have sufficient privileges."
• NX-API Not Found: "NX-API endpoint not found. Verify the device supports NX-API."
• Timeouts: "Request timed out after X seconds"
• Command Errors: Includes command-specific error codes and messages from NX-OS

Limitations

• Maximum 50 devices per multi-device command execution
• Maximum 100 commands per request
• Timeout range: 1-300 seconds
• SSL certificate verification is disabled (assumes self-signed certificates), change this in production!

Troubleshooting

Connection Refused

• Verify NX-API is enabled on the device: show nxapi
• Check network connectivity: ping <device-ip>
• Verify HTTPS port is accessible (default: 443)

Authentication Failed

• Verify credentials in .env file are correct
• Check .env file exists in the project root directory
• Ensure .env file has proper format (no spaces around =)
• Verify the user account exists on the device
• Test credentials by SSH'ing to the device

Command Execution Errors

• Verify command syntax is correct for NX-OS
• Check user has sufficient privileges for the command
• Review NX-OS command output for specific error details

Timeout Issues

• Increase the timeout parameter for slow commands
• Check network latency to devices
• Consider splitting large command batches

Testing

Run with MCP Inspector

npx @modelcontextprotocol/inspector uv run nxos_cli_mcp.py

License

This MCP server is provided as-is under the MIT license.

Contributing

Contributions are welcome! Please ensure:

• Code follows existing patterns and conventions
• All functions have comprehensive docstrings
• Input validation is handled by Pydantic models
• Error messages are clear and actionable

Support

For issues related to:

• NX-API: Consult Cisco NX-OS documentation
• MCP Protocol: Visit https://modelcontextprotocol.io
• This Server: Review error messages and troubleshooting section