NetBox MCP Server

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

• Python 3.11 to 3.14
• A NetBox instance, version 4.2 or newer. Features added later (omit, v2 tokens, /api/authentication-check/) are used when the server detects them
• A NetBox API token with the permissions you want the assistant to have. The token is the real security boundary: a read-only token cannot write, whatever this server's settings are

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

2. Install dependencies:

# Using UV (recommended)
uv sync

# Or using pip
pip install -e .

3. Configure environment variables:

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

4. 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 .

# Setup prek hooks
uv run prek install

Configuration

Environment Variables

# NetBox MCP Server Environment Configuration

# NetBox Connection Details
NETBOX_URL=https://netbox.example.com

# API Token - v2 tokens (nbt_<key>.<token>, NetBox 4.5+) are sent as "Bearer",
# legacy v1 tokens as "Token"
NETBOX_TOKEN=nbt_your-key.your-token

# SSL Configuration
NETBOX_VERIFY_SSL=true
# Total time allowed for one NetBox request, retries included (seconds)
NETBOX_TIMEOUT=30

# Branching (requires the netbox-branching plugin)
# Set NETBOX_BRANCHING_ENABLED true to add the branch tools and the 'branch'
# argument to every tool. Off by default - leave it off on a NetBox without the plugin
NETBOX_BRANCHING_ENABLED=false
# Default branch (name or schema ID) used by every call; empty = main.
# Requires NETBOX_BRANCHING_ENABLED=true
NETBOX_BRANCH=

# Plugin Discovery
# Set NETBOX_PLUGIN_DISCOVERY true to expose plugin models (e.g. netbox_dns.zone)
NETBOX_PLUGIN_DISCOVERY=false

# Read-Only Mode
# Set READ_ONLY_MODE true to hide all write tools (create, update, delete)
READ_ONLY_MODE=false

# Dry-Run Mode
# Set DRY_RUN_MODE true to make every write tool only simulate the change:
# it returns the request it would send and never modifies NetBox
DRY_RUN_MODE=false

# Disabled Tags
# Comma-separated list of tags to disable tools for (empty by default)
# Example: DISABLED_TAGS=delete,graphql,branching
DISABLED_TAGS=

# Logging Configuration
LOG_LEVEL=INFO

# Response Size Limit
# Maximum tool response size in bytes; larger responses are truncated (empty = unlimited)
RESPONSE_MAX_SIZE=

# Rate Limiting
# Set RATE_LIMIT_ENABLED true to enable rate limiting
RATE_LIMIT_ENABLED=false
RATE_LIMIT_MAX_REQUESTS=60
RATE_LIMIT_WINDOW_MINUTES=1

# Tool Search Transform (Optional)
# Set TOOL_SEARCH_ENABLED true to replace full tool listings with search_tools + call_tool
TOOL_SEARCH_ENABLED=false
# Search strategy: bm25 (natural language) or regex (pattern match)
TOOL_SEARCH_STRATEGY=bm25
# Maximum number of tools returned by search_tools
TOOL_SEARCH_MAX_RESULTS=5

# Sentry Error Tracking (Optional)
# Set SENTRY_DSN to enable error tracking and performance monitoring
# SENTRY_DSN=https://your-key@o12345.ingest.us.sentry.io/6789
# Optional Sentry configuration
# SENTRY_TRACES_SAMPLE_RATE=1.0
# SENTRY_SEND_DEFAULT_PII=true
# SENTRY_ENVIRONMENT=production
# SENTRY_RELEASE=1.2.3
# SENTRY_PROFILE_SESSION_SAMPLE_RATE=1.0
# SENTRY_PROFILE_LIFECYCLE=trace
# SENTRY_ENABLE_LOGS=true

# MCP Transport Configuration
# Transport type: 'stdio' (default), 'sse' (Server-Sent Events), or 'http' (HTTP Streamable)
# MCP_TRANSPORT=stdio

# HTTP Transport Settings (used when MCP_TRANSPORT=sse or MCP_TRANSPORT=http)
# Host to bind the HTTP server (default: 127.0.0.1)
# MCP_HTTP_HOST=127.0.0.1
# Port to bind the HTTP server (default: 8000)
# MCP_HTTP_PORT=8000
# Optional bearer token for authentication (leave empty for no auth)
# MCP_HTTP_BEARER_TOKEN=

Available Tools

Object types are named app.model, as NetBox itself names them (dcim.device, ipam.prefix, virtualization.virtualmachine). API paths such as dcim/devices are accepted too. With branching enabled, every tool that reads or writes objects also takes an optional branch argument.

Objects (read)

Specialised (read)

Write

Tool Tags

Every tool is tagged netbox plus a group tag, which DISABLED_TAGS can switch off: objects, search, changelog, status, graphql, ipam, dcim, config, branching, write and delete. Read tools also carry read-only.

Security & Safety Features

Read-Only Mode

Read-only mode hides every write tool - the client only sees the 11 read tools (12 with branching enabled):

READ_ONLY_MODE=true

Dry-Run Mode

Dry-run mode keeps the write tools visible, but none of them changes NetBox. Each one resolves and validates its target, then returns the request it would have sent, flagged "dry_run": true. Updates and deletes also fetch the current object, so the preview shows the values that would change and exactly what would be deleted: