🌐 Nornir MCP Server

A FastMCP server providing network automation tools powered by Nornir and NAPALM.

This server acts as a bridge, exposing Nornir/NAPALM network operations as MCP (Massively Concurrent Processing) tools, making them easily accessible from compatible MCP clients.

✨ Key Features

• Concurrent & Multi-vendor: Leverages Nornir for inventory management and concurrent task execution against network devices using NAPALM for multi-vendor support.

• Expanded Toolset: Provides over 20 tools, including a wide range of NAPALM getters (get_facts, get_interfaces), execution commands (ping, traceroute), and inventory management (list_all_hosts).

• Robust Input Validation: Uses Pydantic models to validate all incoming data for tools, ensuring type safety and preventing errors from invalid inputs.

• Secure Command Execution: Features a configurable command blacklist (conf/blacklist.yaml) to prevent accidental or malicious execution of dangerous commands like reload or erase startup-config via the send_command tool.

• Containerized & Fast: Containerized with Docker 🐳 for easy setup and uses uv for lightning-fast Python dependency management within the container ⚡.

Related MCP server: Cloudflare API MCP Server

🔧 Prerequisites

Before you begin, ensure you have the following installed:

• Docker

• Docker Compose (Usually included with Docker Desktop)

⚙️ Configuration

Before running the server, you must configure your network inventory and device credentials:

1. Navigate to the conf/ directory in the project.

2. Edit : Define your network devices, including their management IP, platform, credentials, and groups.

3. Edit : Define device groups with shared properties.

4. Edit : Set default credentials and connection options.

   • ⚠️ Important Security Note: For production, strongly consider using Nornir's secrets management features to avoid storing plaintext credentials in YAML files.

5. Review : Customize the list of blocked commands and patterns to fit your security policies.

▶️ Running the Server

Once configured, you can easily run the server using Docker Compose:

This command starts the Nornir MCP server in a Docker container, accessible on port 8000 of your host machine. The container now uses run.py as its entrypoint, which supports both development and production modes.

To run the server locally (without Docker), use:

or simply:

This will start the server on 0.0.0.0:8000 using the new entrypoint logic.

🔌 How to connect an MCP client

This project exposes FastMCP over HTTP using the streamable-http transport. The server provides two useful endpoints:

• HTTP API endpoint: http://:/mcp

• SSE endpoint (events): http://:/sse

Notes on transports and client setup:

• The MCP server itself is an HTTP application (FastAPI/Starlette) served by Uvicorn. You should connect MCP clients directly to the /mcp (primary) endpoints using a client that supports the streamable-http transport.

• You do NOT need to run this project in stdio mode for typical HTTP or SSE clients. Previously included instructions referencing running the server in "stdio mode" and proxying it with Supergateway were inaccurate for the normal usage of this repository.

Example MCP client JSON configuration (HTTP/streamable-http):

🧠 Prompts (custom prompt functions)

This server supports registering custom prompt functions that return a list of messages (MCP Prompt format). Prompts let you predefine conversational inputs that MCP clients or LLM-driven agents can call as named prompts. The FastMCP API exposes a @server.prompt() decorator to register functions.

Key features:

• Register synchronous or async prompt functions using @server.prompt().

• Optionally provide a name, title, and description to make prompts discoverable in MCP clients.

• Prompts can return structured messages including resource references (useful for returning file contents or inventory snippets).

How to add a prompt (example):

Async example with a resource:

Usage notes:

• After registering prompts, clients can discover them via the MCP ListPrompts request and call them by name.

• Keep prompt functions lightweight and deterministic; avoid long-running operations inside prompts. If you need data gathered from devices, consider registering a tool and calling it from the prompt or returning a short resource reference that the client can fetch.

Security:

• Prompts run inside the server process; do not perform unsafe file operations or execute untrusted code in prompt functions.

Quick start — Docker (recommended)

1. Build and run with docker-compose (from repo root):

This starts the server in the container and exposes it on port 8000 by default.

Quick start — Local

1. Create and activate a virtual environment.

2. Install runtime dependencies (example):

3. Run the server locally (binds to 0.0.0.0:8000 by default):

Or with uv (recommended when using the included runner):

If you need to change host/port use the --host and --port flags when running run.py.

Security notes

• Inventory YAML files may contain credentials. For production, prefer secrets management (Vault, environment variables, or Nornir secrets plugins) over plaintext YAML.

• The server strips common sensitive keys (username, password, secret) from resources served via resource://inventory/*.

Contributing

• Open an issue or PR for changes. Keep changes small and include tests where appropriate.

License

• MIT