The NetBox MCP server is NetBox Labs' official Model Context Protocol server for NetBox — a read-only bridge that exposes your network source of truth to LLMs and AI agents. Point it at your NetBox instance with an API token, and an AI assistant can query devices, interfaces, IP addresses, and prefixes in plain English, no Python scripting against the REST API required.
That answers the "what." The more interesting question is what you can build with it. This tutorial walks both paths honestly: the DIY route — run the server yourself and wire it to Claude Desktop or your own agent — and the productized route, where NetPilot's NetBox connector lets an AI network engineer read your NetBox records, design a matching lab topology, deploy it on real network operating systems, and rehearse your next change against it before production.
What the NetBox MCP Server Actually Is
MCP (Model Context Protocol) is the open standard for connecting AI models to external tools and data. The official NetBox MCP server implements it for NetBox: a small service that sits in front of your NetBox instance and exposes read-only tools an LLM can call — look up objects, filter by site or role, and pull the changelog. It is read-only by design: the model can look things up, but it cannot create or modify records (official docs).
Worth knowing for context: NetBox Labs has been building AI into NetBox itself. Its commercial platform's MCP integration goes further than the open-source server, adding write access gated behind branching and approval workflows, and NetBox Copilot — its in-product AI assistant — reached general availability in February 2026. The server you can run yourself today, though, is deliberately read-only.
Here is the gap this tutorial closes: a chat assistant connected to NetBox can answer questions about your documented network, but it cannot build anything. The records describe routers; nothing boots one. Everything below is about turning those records into a lab that actually runs.
Path 1: Run the NetBox MCP Server Yourself
If you want full control and are comfortable owning the glue, the DIY path is legitimate and well-documented.
Docker, GitHub, and Claude Desktop
The official server's source lives on GitHub (linked from the docs), and the standard deployment is a container. The setup is two environment variables and a run command:
# The server needs your NetBox URL and an API token.
# Use a read-only token — the server never writes, so the token shouldn't be able to either.
export NETBOX_URL=https://netbox.example.com/
export NETBOX_TOKEN=your-read-only-api-token
# For a network-reachable endpoint (Claude, NetPilot, any remote MCP client),
# also run the container in HTTP transport mode with its own endpoint auth:
export TRANSPORT=http
export HOST=0.0.0.0 PORT=8000
export MCP_AUTH_TOKEN=a-separate-bearer-for-the-endpoint
# ...then start it, publishing the port (exact image name/tag: see the repo README):
docker run --rm -p 8000:8000 \
-e NETBOX_URL -e NETBOX_TOKEN -e TRANSPORT -e HOST -e PORT -e MCP_AUTH_TOKEN \
<netbox-mcp-server-image>Then register the running server in your MCP client's configuration — Claude Desktop, an IDE assistant, or an agent you've written yourself. From that point, "which devices in site DFW01 have interfaces without IP addresses?" is a chat message instead of a pynetbox script.
What you get: fast, natural-language Q&A over your source of truth. What you don't get: a lab. The assistant reads records; deploying network operating systems, generating configs, and validating behavior are all still on you.
NetBox to Containerlab, Before AI: nrx and netbox-nrx-clab
Credit where due — the "source of truth drives the lab" idea predates agents. Netreplica's nrx exports device and interface data from NetBox into a Containerlab topology file, and the srl-labs/netbox-nrx-clab lab demonstrates the full NetBox-to-Containerlab pipeline end to end. If you want a scripted, deterministic export with no AI in the loop, this is the proven route.
The honest trade-off: nrx generates topology YAML. Sourcing node images, producing per-device configurations, deploying, and verifying that the lab behaves like the records say it should — that remains manual work, and the pipeline predates the MCP era, so nothing about it is conversational.
Path 2: NetPilot's NetBox Connector
The productized route packages the whole loop — read the source of truth, design, deploy, validate — behind one agent. Setup happens in the chat itself at app.netpilot.io:
- Click the plus button in the chat composer and choose Connectors.
- Add a label (say,
netbox-prod), the HTTPS URL of your NetBox MCP server, and the endpoint's auth token — the bearer token your MCP server expects for inbound connections (for a self-hosted server this is the server's own auth token, e.g.MCP_AUTH_TOKEN, not your NetBox API token). - Click Add & test connection. NetPilot performs a live MCP handshake against the endpoint, and the connector is enabled only when the test passes.
The server from Path 1 is reusable here — with one wiring difference: NetPilot connects over the network, so the server must be serving streamable HTTP on a public HTTPS endpoint (a local stdio wiring for Claude Desktop isn't reachable from outside your machine). Three guardrails are worth calling out, because they're structural rather than policy:
- Read-only allow-list by construction. The agent is granted only the intersection of what your server advertises and NetPilot's curated read-only allow-list — exact tool names, no wildcards. Even if a server exposed a mutating tool, the agent would never see it.
- Write-only tokens. Connector tokens are encrypted at rest and can never be read back out of the UI or API.
- HTTPS-only endpoints, validated at add time by that live handshake.
Connections are per-user, and you can add several per provider — a production and a staging NetBox side by side, disambiguated by label in plain English.
Tutorial: Build a Lab from NetBox and Rehearse a Change
Here is the loop end to end, using a site called DFW01 as the example. Each step leads with the agent prompt; the raw CLI is always available underneath if you prefer to verify by hand.
Step 1: Pull the site from your source of truth
"Using my netbox-prod connection, pull site DFW01 — devices with roles and device types, interfaces and their connections, IP addresses, and prefixes. Summarize the site for me."
The agent calls the read-only tools on your NetBox MCP server and returns a structured inventory: the two edge routers, the distribution pair, the access layer, addressing per link. No export scripts, no CSV wrangling.
Step 2: Design the topology from the records
"Design a lab topology that mirrors DFW01 — same roles, same links, same addressing. Pick lab node types that match each platform, and show me the topology before deploying anything."
The agent maps each NetBox device record to an emulated node type and drafts the topology and per-device configurations. This step is deliberately interactive: NetBox records describe hardware, and you confirm which network OS stands in for which platform before anything runs.
Step 3: Deploy on real network operating systems
"Looks right. Deploy it."
NetPilot deploys the lab in the cloud in about two minutes — real NOS instances with real CLIs, not a mathematical model of one. That distinction matters for what comes next: you can SSH into these devices, run debugs, and watch protocols converge, which is the difference between a digital twin you can execute and one you can only query.
Step 4: Verify — agent first, SSH always
"Check the control plane across all DFW01 lab devices — interface status, routing neighbors, and whether live addressing matches the NetBox records."
The agent translates that into the right syntax per device, runs the checks across every node in parallel, and returns one consolidated table with anomalies flagged. Direct CLI is always there too — SSH into any node and verify by hand:
show ip interface brief
show ip bgp summary
show ip routeUse the agent for the fast path across ten devices; use the CLI when you want to drill into one.
Step 5: Rehearse the change with a pre/post diff
"Capture pre-change state — routing tables, neighbor sessions, interface counters. Then apply the planned change: move DFW01's uplinks to the new transit peer. Diff post-change state against the baseline and flag anything that moved that shouldn't have."
This is the payoff. The agent snapshots the baseline, applies the change in the lab, and hands you a diff of what actually happened — the same evidence you'd want before a maintenance window, produced against a replica built from your own records. That rehearsal loop is the core of pre-change validation.
The loop in one line: NetBox describes the network, the agent builds it on real NOSes, the change gets rehearsed with a pre/post diff — and you walk into the maintenance window having already seen the result.
What This Workflow Can't Do
Honesty section, because the limits are real:
- No write-back to NetBox. The connector is read-only in both spirit and mechanism. If the rehearsal reveals that your records are stale, the agent reports it — updating NetBox is your job, in NetBox.
- Your NetBox, self-hosted, for now. The verified path today is a NetBox MCP server you host yourself. If you run your own NetBox and its MCP server, you're covered.
- The lab is only as good as the records. A stale source of truth produces a stale twin. Running a drift check between NetBox and the live network first is the right hygiene — there's a ready-made prompt for that below.
- Connections are per-user. Team-shared connectors aren't available yet.
Beyond NetBox: the Starting Point, Not the List
NetBox is one of three connectors that ship in-product on every plan today — alongside Nautobot, Network to Code's 2021 fork of NetBox (point NetPilot at your Nautobot MCP server the same way), and a Nornir live-CLI connector that runs read-only show commands on real gear with device credentials brokered from your Nautobot at call time (NetPilot stores neither credentials nor inventory).
But the trio is the starting point, never the list. NetPilot is MCP-connectable both ways. Connect your own AI agents to NetPilot's MCP server to build and validate labs on demand — and let NetPilot's agent connect to your stack (NetBox/Nautobot, Git, ServiceNow/Jira, CI/CD) to build pre-change validation labs from your real configs. Included with Signature & Enterprise. Every integration is custom-built to fit your workflow — if it has an API, NetPilot connects to it. The full picture, including the security model, lives on the integrations page.
FAQ
How do I run the NetBox MCP server in Docker?
Run the official container with NETBOX_URL pointing at your NetBox instance and NETBOX_TOKEN holding a read-only API token — and, for a network-reachable endpoint, TRANSPORT=http with HOST/PORT, a separate MCP_AUTH_TOKEN for endpoint auth, and the port published (-p 8000:8000). Then register the server's endpoint in your MCP client's configuration (Claude Desktop or your own agent). The exact image name and run command are in the official documentation. Use a read-only token: the server never writes, so its credentials shouldn't be able to either.
Is the NetBox MCP server read-only?
Yes. The official open-source NetBox MCP server is read-only by design — it exposes lookup and query tools, not create/update/delete (NetBox Labs docs). Write access exists only in NetBox Labs' commercial platform, where its MCP integration gates changes behind branching and approval workflows. NetPilot's connector adds a second, independent layer: a curated read-only allow-list, so mutating tools are never exposed to the agent regardless of what a server advertises.
Can an AI agent build a Containerlab topology from NetBox?
Yes, two ways. The scripted way: netreplica's nrx exports NetBox data into a Containerlab topology file — proven, deterministic, but configs and validation stay manual. The agent way: a platform like NetPilot reads your NetBox records over MCP, designs the topology, generates per-device configs, deploys it on real network operating systems, and validates the result — all from plain-English prompts, with SSH access to every node.
How does NetPilot connect to NetBox?
Through a connector you add from the chat composer: a label, the HTTPS URL of your NetBox MCP server, and the endpoint's bearer token (the server's own auth token, not your NetBox API token), followed by a live add-and-test MCP handshake — the connector enables only when the test passes. Access is read-only by construction (curated allow-list, exact tool names), tokens are encrypted at rest and write-only, and endpoints are HTTPS-only. The verified path today is a NetBox MCP server you host yourself.
Copy-paste ready: the full rehearsal-loop prompt is in our public examples repo — netbox-site-twin-rehearsal.md, plus sot-drift-detection.md for checking your records against the live network first.
Ready to point an agent at your source of truth? See how the connectors work on the NetPilot integrations page, or add your NetBox in the chat and build your first site twin today.