NetBox MCP server

NetBox MCP Server

<!-- mcp-name: io.github.mhajder/netbox-mcp -->

NetBox MCP Server is a Python-based Model Context Protocol (MCP) server that gives AI assistants structured access to NetBox - the source of truth for network infrastructure (DCIM and IPAM). A small set of generic tools covers all 139 core object types of NetBox 4.7 (and plugin types, if enabled), plus specialised tools for search, change logs, GraphQL, free IP/prefix/VLAN allocation, cable tracing, config rendering and (optionally) netbox-branching. Writes can be hidden entirely (read-only mode) or simulated (dry-run mode).

Features

Core Features

• Query any NetBox object type with filtering, ordering and pagination through one tool
• Keep responses small with fields, omit and brief - the tools steer the model to use them
• Search many object types at once, with explicit reporting of failed and truncated types
• Read the change log (who changed what, when) and NetBox status/version/plugins
• Run read-only GraphQL queries for nested data in one round trip
• List free IPs, prefixes, VLANs and ASNs; trace cable paths; render device configs

Management Operations

• Create, update and delete any object type, singly or in bulk (NetBox runs a bulk write as one transaction)
• Allocate the next free IP, prefix, VLAN or ASN atomically
• Optionally stage changes in a netbox-branching branch instead of main
• Describe an object type's writable fields and choices before writing

Advanced Capabilities

• Read-only mode hides every write tool; dry-run mode turns every write into a preview
• NetBox v2 (Bearer nbt_...) and legacy v1 (Token ...) API tokens
• Plugin object type discovery (e.g. netbox_dns.zone)
• Filter validation that rejects filters NetBox would silently ignore (__in, multi-hop lookups)
• Retries on 429/5xx without ever replaying a create after a server error
• Tag-based tool filtering, optional tool-search transform, rate limiting and response size limit
• Bearer token authentication for HTTP transport
• Multiple transport options (STDIO, SSE, HTTP)
• Optional Sentry integration for error tracking

Installation

Prerequisites

tokens, /api/authentication-check/) are used when the server detects them

• Python 3.11 to 3.14
• A NetBox instance, version 4.2 or newer. Features added later (omit, v2

token is the real security boundary: a read-only token cannot write, whatever this server's settings are

• A NetBox API token with the permissions you want the assistant to have. The

Quick Install from PyPI

The easiest way to get started is to install from PyPI:

# Using UV (recommended)
uvx netbox-mcp

# Or using pip
pip install netbox-mcp

Remember to configure the environment variables for your NetBox instance before running the server:

# Create environment configuration
export NETBOX_URL=https://netbox.example.com
export NETBOX_TOKEN=nbt_your-key.your-token

Install from Source

1. Clone the repository:

git clone https://github.com/mhajder/netbox-mcp.git
cd netbox-mcp

1. Install dependencies:

# Using UV (recommended)
uv sync

# Or using pip
pip install -e .

1. Configure environment variables:

cp .env.example .env
# Edit .env with your NetBox URL and API token

1. Run the server:

# Using UV (recommended)
uv run netbox-mcp

# Or using the installed command directly
netbox-mcp

Using Docker

A Docker image is available on GitHub Packages for easy deployment.

docker pull ghcr.io/mhajder/netbox-mcp:latest

Development Setup

For development with additional tools:

# Clone and install with development dependencies
git clone https://github.com/mhajder/netbox-mcp.git
cd netbox-mcp
uv sync --group dev

# Run tests
uv run pytest

# Run with coverage
uv run pytest --cov=src/

# Run linting and formatting
uv run ruff check .
uv run ruff format .

# Run type checking
uv run ty check .

Shortened. The full README is on GitHub.