Nornir

You set up and run a FastMCP server that exposes Nornir and NAPALM operations as MCP tools, enabling you to automate multi-vendor networks concurrently through a single HTTP interface and real-time events.

How to use

Connect an MCP client to the primary HTTP endpoint to start issuing MCP tools against your network inventory. You will access the server via the streamable-http transport over HTTP. Use the HTTP API endpoint to send requests and receive responses, and you can subscribe to events through the Server-Sent Events endpoint for live updates. The server exposes common MCP tool capabilities such as retrieving device facts, listing interfaces, pinging devices, performing traceroutes, and managing inventory, all orchestrated through Nornir for concurrency and NAPALM for multi-vendor support.

Recommended client setup pattern: point your MCP client to the primary HTTP URL and choose the transport to be streamable-http. You can also listen to the SSE endpoint for event streams. Typical usage focuses on querying device data and running lightweight operational commands against your inventory in a safe, concurrent manner. If you need to inspect or modify the inventory, ensure your client has the appropriate permissions and consult the configured groups and defaults to understand how credentials are applied.

How to install

Prerequisites you must have before starting:

• Docker is required to run the server in a container for quick setup and consistent environments.
• Docker Compose orchestrates the multi-container setup and exposes the MCP service on port 8000 by default.

Choose your preferred installation path and follow the steps below.

docker-compose up --build -d

If you want to run the server locally without Docker, proceed with a Python-based setup as shown.

python run.py

To run in development mode with the included runner, you can use UVicorn for fast startup.

uv run ./run.py

If you need to customize the host or port, pass the appropriate flags when starting the server. By default, the server binds to 0.0.0.0:8000.

Configuration and security notes

Before starting, configure your network inventory and device credentials under the conf/ directory. You should edit the following files to define devices, groups, and defaults: hosts.yaml, groups.yaml, and defaults.yaml. For production, consider using secrets management to avoid storing plaintext credentials in YAML files.

Security: Review the blacklist.yaml to block dangerous commands from being sent via the tool that executes commands on devices. This helps prevent unintended or malicious actions like reloads or erasing startup configurations.

The server also exposes resource endpoints for inventory and topology, which you can reference when building clients or custom prompts. These resources help you surface sanitized device data and topology information securely.

Additional notes

Endpoints you will use when connecting clients are the primary HTTP API at /mcp and the SSE events endpoint at /sse. Provide a client configuration that points to http://<host>:8000/mcp with the streamable-http transport. The server runs as an HTTP application (FastAPI/Starlette) served by Uvicorn, so you do not need a stdio proxy setup for typical HTTP/SSE clients.

If you are new to MCP prompts, you can register custom prompt functions that return messages or resources. This enables pre-defined conversational prompts that MCP clients or automated agents can invoke by name to fetch inventory summaries or file-like resources.

Available tools

get_facts

Retrieve device facts such as model, OS version, and capabilities using NAPALM-backed getters.

get_interfaces

Fetch interface details and status from devices managed in the inventory.

ping

Execute ping tests to verify reachability of devices in the inventory.

traceroute

Run traceroute to map the path to a target across the network.

list_all_hosts

Return the full list of hosts in the inventory with sanitized fields.

send_command

Send arbitrary commands to devices through a controlled interface, subject to security blacklist rules.