# Cisco NXOS MCP Server

> A simple MCP (Model Context Protocol) that interacts with Cisco NX-OS devices

- **Type:** MCP server
- **Install:** `agentstack add mcp-cpaggen-cisco-nxos-mcp-server`
- **Verified:** Pending review
- **Seller:** [cpaggen](https://agentstack.voostack.com/s/cpaggen)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [cpaggen](https://github.com/cpaggen)
- **Source:** https://github.com/cpaggen/Cisco_NXOS-MCP_Server

## Install

```sh
agentstack add mcp-cpaggen-cisco-nxos-mcp-server
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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](https://github.com/astral-sh/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):

```bash
# 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:

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

3. Set up authentication credentials:

Create a `.env` file from the template:

```bash
cp .env.example .env
```

Edit `.env` and add your credentials:

```env
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:
```bash
code ~/Library/Application\ Support/Claude/claude_desktop_config.json
```

Add the NX-OS CLI MCP server to the `mcpServers` section:
```json
{
  "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:
```powershell
notepad %APPDATA%\Claude\claude_desktop_config.json
```

Add the NX-OS CLI MCP server to the `mcpServers` section:
```json
{
  "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:
```bash
code ~/Library/Application\ Support/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/cline_mcp_settings.json
```

Add the server configuration:
```json
{
  "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:
```powershell
notepad %APPDATA%\Code\User\globalStorage\rooveterinaryinc.roo-cline\settings\cline_mcp_settings.json
```

Add the server configuration:
```json
{
  "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 `
- 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
```bash
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

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [cpaggen](https://github.com/cpaggen)
- **Source:** [cpaggen/Cisco_NXOS-MCP_Server](https://github.com/cpaggen/Cisco_NXOS-MCP_Server)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: flagged — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-cpaggen-cisco-nxos-mcp-server
- Seller: https://agentstack.voostack.com/s/cpaggen
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.