Nornir Server

License: MIT Python 3.12+ MCP Ruff

An enterprise-ready Model Context Protocol (MCP) server that brings the power of Nornir to LLMs like Claude. It seamlessly integrates NAPALM for structured data retrieval and Netmiko for flexible CLI execution, enabling natural language orchestration of complex network infrastructure.

---

🚀 Overview

The Nornir MCP Server provides a specialized set of tools for network engineers and AI agents to interact with multi-vendor environments safely and efficiently.

• Multi-Vendor Support: Standardized interaction for Cisco (IOS, NX-OS, XR), Arista (EOS), Juniper (Junos), and 100+ others.
• Dual-Engine Architecture: Combines NAPALM's normalized getters with Netmiko's robust SSH command execution.
• Intelligent Filtering: Schema-agnostic device selection by hostname, group, or platform.
• Security First: Built-in command blacklisting, input validation (Pydantic), and backup path restrictions.
• Per-Call Inventory Reloading: Every MCP tool invocation reloads config.yaml and inventory data from disk.
• Production Ready: Comprehensive logging and asynchronous execution.

---

📋 Table of Contents

• Installation
• Quick Start
• Lab Environment
• Available Tools
• Configuration
• Claude Integration
• Security
• Development
• Testing

---

🛠 Installation

Using uv (Recommended)

# Install as a global tool
uv tool install git+https://github.com/sydasif/nornir-mcp-server.git

# Upgrade to latest
uv tool upgrade nornir-mcp-server

Using pip

pip install git+https://github.com/sydasif/nornir-mcp-server.git

---

⚡ Quick Start

1. Initialize Configuration:

   Create a config.yaml and basic inventory files in your working directory. See Minimal Inventory Example below.

2. Launch the Server:

   
   nornir-mcp
   

3. Verify Inventory:

   The server will look for config.yaml in the current directory to load your Nornir inventory.

---

📦 Minimal Inventory Example

To get started quickly, create these three files in your project root:

hosts.yaml

R1:
  hostname: 192.168.1.1
  platform: ios
  groups:
    - cisco_ios

groups.yaml

cisco_ios:
  platform: ios
  username: admin
  password: password

defaults.yaml

# Global defaults
data:
  site: NYC

config.yaml

inventory:
  plugin: SimpleInventory
  options:
    host_file: "hosts.yaml"
    group_file: "groups.yaml"
    defaults_file: "defaults.yaml"

---

🧪 Lab Environment

For a ready-to-use Containerlab lab with Cisco CSR1000v and Arista cEOS devices, see the companion repository: nornir-mcp-lab

Prerequisites: Containerlab, Docker, Python 3.12+

---

🧰 Available Tools

The server exposes 5 tools categorized by operational intent. All tools support individual filter parameters for device selection.

Filter Parameters:

• filter_name: Filter by device name in inventory
• filter_hostname: Filter by specific hostname or IP address
• filter_group: Filter by group membership (e.g., "cisco", "arista")
• filter_platform: Filter by platform (e.g., "eos", "ios", "junos")

All filter parameters are optional. When multiple filters are provided, they are combined with AND logic.

Category	Tool	Description
Inventory	list_devices	List hosts, groups, and metadata.
Monitoring	fetch_data	Generic access to any NAPALM getter (ARP, VLAN, etc.).
	show_commands	Execute arbitrary show commands safely.
Management	apply_config	Deploy configuration changes with validation.
	backup_configs	Securely save configurations to local disk.

---

⚙️ Configuration

Every MCP tool call reloads config.yaml from the current working directory. The server does not cache a long-lived Nornir instance between requests.

Nornir Setup (config.yaml)

inventory:
  plugin: SimpleInventory
  options:
    host_file: "hosts.yaml"
    group_file: "groups.yaml"
    defaults_file: "defaults.yaml"

runner:
  plugin: threaded
  options:
    num_workers: 100

logging:
  enabled: true
  level: INFO

Command Security

The server includes a built-in security engine that validates all CLI commands against a multi-stage validation system before execution. This prevents accidental or malicious use of destructive commands while minimizing false positives for read-only operations.

Security Features:

• Read-Only Enforcement: Tools like show_commands enforce an allowlist prefix (e.g., show, display, get, ping, traceroute).
• Smart Denylist: Destructive keywords (erase, format, delete, reload) are blocked only when they appear as the first token of a command. This allows legitimate commands like show reload history while blocking a bare reload.
• Chaining & Redirection Protection: Prevents the use of ;, &&, >, and < to ensure single-command integrity.
• Path Sandboxing: Configuration backups are protected against directory traversal attacks (..).

---

🤖 CLI Integration

Add the following to your claude config:

{
  "mcpServers": {
    "nornir": {
      "command": "nornir-mcp"
    }
  }
}

Add the following to your opencode config:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "nornir": {
      "type": "local",
      "command": ["nornir-mcp"]
    }
  }
}

Try these prompts:

• "Show me all core routers in the US-West region."
• "Are there any BGP neighbors down on R1?"
• "Backup the running configuration of all Arista switches."
• "Check if there are any errors on the interfaces of the edge-group."

---

🔒 Security

• Command Validation: All CLI inputs pass through a multi-stage built-in denylist filter (Keywords and Patterns).
• Path Sandboxing: Configuration backups are restricted to the defined root directory to prevent traversal.

---

👨‍💻 Development

# Clone and setup
git clone https://github.com/sydasif/nornir-mcp-server.git
cd nornir-mcp-server
uv sync

# Run tests
uv run pytest

# Lint and Format
uv run ruff check . --fix
uv run ruff format .

If uv run is unstable in the local environment, use .venv/bin/pytest and .venv/bin/ruff directly.

Relevant internal paths:

• src/nornir_mcp/services/runner.py: shared async task execution. Mandatory entry point for all network tasks; accepts filter kwargs (name, hostname, group, platform).
• src/nornir_mcp/services/inventory.py: shared inventory loading and filtering helper. Reloads config.yaml from disk on every call. Accepts filter kwargs directly.
• src/nornir_mcp/services/napalm.py: shared NAPALM getter execution helper used by monitoring and backup tools. Accepts filter kwargs directly.
• src/nornir_mcp/tools/monitoring.py: monitoring tools for NAPALM getters and Netmiko show commands.
• src/nornir_mcp/tools/management.py: management tools for configuration deployment and backups.

---

✅ Testing

The repository includes a pytest suite under tests/ covering filters, inventory loading, inventory tools, monitoring tools, NAPALM helper behavior, security validation, runner error handling, and backup behavior.

# Run the full test suite
uv run pytest

# Fallback if uv run is unstable
.venv/bin/pytest

---

📄 License

This project is licensed under the MIT License. See LICENSE for details.

---

Built with ❤️ for Network Automation