nornir-napalm-mcp

A FastMCP server that exposes live network device state to AI assistants via NAPALM getters. Nornir handles inventory loading and concurrent device connections over SSH, eAPI, and NETCONF.

All operations areread-only— no configuration push is exposed.

- Lazy initialization— server starts even with a broken inventory, exposing the tool catalogue for inspection.
- Singleton caching— Nornir instance is initialized once and reused across requests. Failed-device quarantine (failed_hosts) is reset before every call so dropped devices are available again on the next request.
- Flexible filtering— filter by device name, group, or platform on any tool.
- HTTP and STDIO transport— run locally for Claude Desktop or expose over HTTP.

The server requires a Nornir configuration file, provided via theNORNIR_CONFIGenvironment variable.

- Copy the included example config to the project root (or any path you prefer):

- Editconfig.yamlto point at your inventory files. A minimal config looks like:

--- inventory: plugin: SimpleInventory options: host_file: "inventory/hosts.yaml" group_file: "inventory/groups.yaml" defaults_file: "inventory/defaults.yaml" runner: plugin: threaded options: num_workers: 10 logging: enabled: false

Note: The inventory files referenced must exist relative to this config file.

Register this server with any MCP client (Claude Desktop, VS Code, etc.) by adding the following to your project's.mcp.json:

{ "mcpServers": { "nornir": { "command": "uvx", "args": [ "--from", "git+https://github.com/sydasif/nornir-napalm-mcp", "nornir-napalm-mcp" ], "env": { "NORNIR_CONFIG": "/absolute/path/to/config.yaml" } } } }

Usenornir_run_getterwith any of these:

NORNIR_CONFIG=/path/to/config.yaml uv run nornir-napalm-mcp

NORNIR_CONFIG=/path/to/config.yaml uv run nornir-napalm-mcp --transport http --host 0.0.0.0 --port 8000

NORNIR_CONFIG=/path/to/config.yaml uv run python -m nornir_napalm_mcp

nornir-napalm-mcp/ ├── nornir_napalm_mcp/ │ ├── __init__.py # Package version │ ├── __main__.py # python -m support │ ├── main.py # CLI entry point (argparse, transport selection) │ ├── models.py # Pydantic data models (InventoryDevice, GetterInfo, HostResult) │ ├── runner.py # Nornir init, config loading, singleton caching, NornirLike protocol │ ├── tasks.py # Task helpers: device filtering, execution, result normalization │ ├── introspection.py # NAPALM getter discovery per platform │ ├── server.py # FastMCP server instance and the 7 tool definitions │ └── py.typed # PEP 561 marker for downstream type checking ├── tests/ │ ├── conftest.py # Fake Nornir stubs and pytest fixtures │ ├── test_server.py # Unit tests for the 7 MCP tools and inventory listing │ ├── test_tasks.py # Unit tests for device filtering and task execution │ ├── test_cli.py # Unit tests for the CLI entry points │ └── test_runner.py # Unit tests for config loading and path expansion ├── config.example.yaml # Example Nornir configuration ├── pyproject.toml # Build config, dependencies, and tool settings ├── uv.lock # Locked dependencies └── README.md

# Install dependencies uv sync # Run tests uv run pytest # Run tests with coverage uv run pytest --cov=nornir_napalm_mcp --cov-branch # Lint uv run ruff check . # Auto-fix lint issues uv run ruff check --fix . # Format uv run ruff format . # Type check (strict mode) uv run mypy .

- Python 3.12+— use modern syntax (f-strings,match,str.removeprefix)
- Type hints— required on all function signatures (mypy --strict)
- Docstrings— Google-style withArgs:,Returns:,Raises:
- Tests— AAA pattern, one assertion per logical check, usepytestfixtures
- Linting—ruffwithE,F,I,UPrules

feat(server): add nornir_ping tool fix(runner): handle missing NORNIR_CONFIG gracefully refactor: extract _run_nornir_task helper test: add runner config expansion tests

Test against real devices using thenetlab-demotest lab with Cisco devices via Containerlab.

You built it, now get users! GoToMarket MCP server