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):

2. Install dependencies using uv:

3. Set up authentication credentials:

Create a .env file from the template:

Edit .env and add your credentials:

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:

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

Windows:

Edit the Claude Desktop configuration file:

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

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

Visual Studio Code

macOS:

Edit the VS Code MCP settings file:

Add the server configuration:

Windows:

Edit the VS Code MCP settings file:

Add the server configuration:

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:

Verify NX-API is running:

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

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