NetBox MCP Server — AI Access to Live Infrastructure Data

Problem

AI coding assistants have no awareness of live infrastructure. When writing automation scripts, generating configs, or troubleshooting issues, engineers constantly interrupt their workflow to copy-paste data from NetBox into their AI tool: IP addresses, VLAN IDs, device hostnames, interface names, circuit IDs. Each lookup breaks flow, and each manual transcription is an opportunity to introduce errors.

The problem compounds on larger tasks. Generating a config for a new site might require a dozen separate NetBox lookups — site details, device list, IP allocations, VLAN assignments, upstream circuit. That’s a dozen copy-paste operations before the AI can do any useful work.

Solution

Built an MCP (Model Context Protocol) server that exposes NetBox’s full inventory as structured tools for AI assistants. AI tools query live NetBox data directly: list sites, look up devices by site or role, find IP allocations, resolve prefix details, enumerate VLANs, trace cable paths between interfaces.

The server is read-only by design, making it safe to connect to production NetBox instances. It works with any MCP-compatible client — Claude Code, Claude Desktop, and the growing ecosystem of MCP-aware tools. Published as open-source with an Apache 2.0 license so the network engineering community can adopt and extend it.

Architecture

AI Assistant (Claude Code / Claude Desktop)
    │
    │  MCP Protocol (stdio transport)
    ▼
netbox-mcp-server (Python)
    │
    ├── 13 MCP Tools
    │       ├── get_sites / get_site_detail
    │       ├── get_devices / get_device_detail
    │       ├── get_interfaces
    │       ├── get_ip_addresses / get_prefixes
    │       ├── get_vlans
    │       ├── get_circuits / get_circuit_detail
    │       └── trace_cable_path
    │
    └── NetBox REST API (paginated, token auth)
            └── NETBOX_URL + NETBOX_TOKEN (env vars)

Docker deployment:
    docker run -e NETBOX_URL=... -e NETBOX_TOKEN=... netbox-mcp-server

Responses are paginated server-side to handle large NetBox inventories without overwhelming the AI context window. Each tool returns structured data with consistent field names regardless of NetBox version quirks.

Key Decisions

Read-only by design. The server has no write tools — no device creation, no IP allocation, no config push. This was a deliberate scope decision, not a technical limitation. Production infrastructure data is too consequential for an AI to modify without explicit human review. A read-only MCP server is safe to connect to any NetBox instance; a read-write one requires careful access controls before anyone would trust it near production.

Paginated responses. Large NetBox instances have thousands of devices and tens of thousands of IP addresses. Returning everything in a single response would overflow AI context windows and be slow. The server handles pagination transparently, fetching pages from the NetBox API and returning results in manageable chunks that fit within AI tool call response limits.

Docker-first deployment. Network teams typically don’t want to manage Python virtualenvs on jump hosts. A single docker run command with two environment variables gets the server running. The Docker image includes all dependencies pinned to known-good versions, avoiding the “works on my machine” problem for a tool that different teams will deploy in different environments.

Environment-based configuration. NetBox URL and API token are the only required configuration, both passed as environment variables. No config files, no YAML, no setup wizard. This makes the server easy to deploy in CI/CD pipelines, Docker Compose stacks, and automated provisioning workflows.

Results

13 MCP tools covering all major NetBox object types: sites, devices, interfaces, IPs, prefixes, VLANs, circuits, cable traces
Published v1.0.0 release on GitHub with Apache 2.0 license
Docker image ready for docker run deployment with two environment variables
Compatible with Claude Code and Claude Desktop MCP configurations
Open-source for community adoption and extension
Paginated responses handle NetBox instances of any size

How This Scales

Write tools (gated) — Add device update, IP allocation, and VLAN assignment tools behind an explicit NETBOX_MCP_ALLOW_WRITES=true environment variable. Off by default, requiring conscious opt-in before anything can modify production data.
Multi-NetBox support — Some organizations run separate NetBox instances for different environments (prod/lab/staging). Support multiple NETBOX_URL/TOKEN pairs with per-tool instance selection.
Other IPAM platforms — The MCP interface abstracts the data source. The same tool signatures could be implemented against phpIPAM, Nautobot, or Infrahub, making the AI assistant IPAM-agnostic.
Ansible inventory generation — A composite tool that queries devices by site and role, then formats the result as an Ansible inventory — removing another manual step from network automation workflows.

Tech Stack

Protocol: MCP (Model Context Protocol, stdio transport)
Language: Python
NetBox integration: NetBox REST API (requests, token auth, pagination)
Deployment: Docker (single-container, env-var config)
License: Apache 2.0
Compatibility: Claude Code, Claude Desktop, any MCP-compatible client