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, prefix utilization, free rack space, cable tracing and connecting, config rendering, custom scripts 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
• Compute prefix utilization (as the NetBox UI shows it) and find racks with room for a device

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
• Connect ports with a cable, naming them by device and port name
• Run NetBox custom scripts (changes rolled back unless commit is set)
• 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.15
• 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 pippip install netbox-mcp

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

# Create environment configurationexport NETBOX_URL=https://netbox.example.comexport NETBOX_TOKEN=nbt_your-key.your-token

Install from Source

1. Clone the repository:

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

2. Install dependencies:

# Using UV (recommended)uv sync
# Or using pippip 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 directlynetbox-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 dependenciesgit clone https://github.com/mhajder/netbox-mcp.gitcd netbox-mcpuv sync --group dev
# Run testsuv run pytest
# Run with coverageuv run pytest --cov=src/
# Run linting and formattinguv run ruff check .uv run ruff format .
# Run type checkinguv run ty check .
# Setup prek hooksuv run prek install

🔧 Configuration

Environment Variables

# NetBox MCP Server Environment Configuration
# NetBox Connection DetailsNETBOX_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 ConfigurationNETBOX_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 pluginNETBOX_BRANCHING_ENABLED=false# Default branch (name or schema ID) used by every call; empty = main.# Requires NETBOX_BRANCHING_ENABLED=trueNETBOX_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 NetBoxDRY_RUN_MODE=false
# Disabled Tags# Comma-separated list of tags to disable tools for (empty by default)# Example: DISABLED_TAGS=delete,graphql,branchingDISABLED_TAGS=
# Logging ConfigurationLOG_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 limitingRATE_LIMIT_ENABLED=falseRATE_LIMIT_MAX_REQUESTS=60RATE_LIMIT_WINDOW_MINUTES=1
# Tool Search Transform (Optional)# Set TOOL_SEARCH_ENABLED true to replace full tool listings with search_tools + call_toolTOOL_SEARCH_ENABLED=false# Search strategy: bm25 (natural language) or regex (pattern match)TOOL_SEARCH_STRATEGY=bm25# Maximum number of tools returned by search_toolsTOOL_SEARCH_MAX_RESULTS=5
# Sentry Error Tracking (Optional)# Set SENTRY_DSN to enable error tracking and performance monitoring# SENTRY_DSN=https://[email protected]/6789# Optional Sentry configuration# SENTRY_TRACES_SAMPLE_RATE=1.0# SENTRY_SEND_DEFAULT_PII=false# 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)# 'streamable-http' is accepted as an alias for 'http'. Any other value stops# the server at startup.# 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=# Set NETBOX_TOKEN_PASSTHROUGH true to make every client authenticate with its own# NetBox API token (Authorization: Bearer <token>); NetBox then applies that user's# permissions. NETBOX_TOKEN is ignored. Cannot be combined with MCP_HTTP_BEARER_TOKEN# NETBOX_TOKEN_PASSTHROUGH=false

🧰 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, scripts, 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 13 read tools (14 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:

DRY_RUN_MODE=true

READ_ONLY_MODE takes precedence: when both are set, write tools are hidden.

NetBox Branching

With the netbox-branching plugin, changes can be staged in a branch and reviewed before they are merged into main. Branching support is off by default, so a NetBox without the plugin gets no branch tools and no branch argument. Enable it with:

NETBOX_BRANCHING_ENABLED=true

This adds netbox_list_branches and netbox_create_branch, and a branch argument (a branch name or its schema ID) to every other tool. To send every call to one branch by default:

NETBOX_BRANCH=assistant-changes

Setting NETBOX_BRANCH without NETBOX_BRANCHING_ENABLED=true is a configuration error: the server refuses to start rather than silently writing to main.

Branch names are resolved to the schema ID that the X-NetBox-Branch header needs. Merging, syncing and reverting are deliberately not exposed as tools - they belong in a human review step.

Plugin Discovery

NETBOX_PLUGIN_DISCOVERY=true

The first time a call names an unknown type (or netbox_list_object_types runs), the server reads /api/core/object-types/ and adds every plugin model with a REST endpoint (for example netbox_dns.zone). Plugin types never shadow core types. If discovery fails, the core types keep working.

Tag-Based Tool Filtering

You can disable specific categories of tools by setting disabled tags. For example, allow creates and updates but never deletes:

DISABLED_TAGS=delete

Response Size Limit

Large NetBox objects add up quickly. RESPONSE_MAX_SIZE truncates any tool response above the given number of bytes:

RESPONSE_MAX_SIZE=200000

Tool Search for Large Toolsets

FastMCP tool search can reduce prompt size for servers with many tools. When enabled, list_tools returns two synthetic tools:

• search_tools: Finds matching tools and returns their full schemas
• call_tool: Executes any discovered tool by name

Enable it with:

TOOL_SEARCH_ENABLED=trueTOOL_SEARCH_STRATEGY=bm25      # bm25 or regexTOOL_SEARCH_MAX_RESULTS=8      # optional, default is 5

bm25 supports natural language queries, while regex uses a regex pattern input for deterministic matching.

Tool search respects existing visibility controls (read-only mode and disabled tags).

Rate Limiting

The server supports rate limiting to control API usage and prevent abuse. If enabled, requests are limited per client using a sliding window algorithm.

Enable rate limiting by setting the following environment variables in your .env file:

RATE_LIMIT_ENABLED=trueRATE_LIMIT_MAX_REQUESTS=60    # Maximum requests allowed per window (default: 60)RATE_LIMIT_WINDOW_MINUTES=1   # Window size in minutes

If RATE_LIMIT_ENABLED is set to true, the server will apply rate limiting middleware. Adjust RATE_LIMIT_MAX_REQUESTS and RATE_LIMIT_WINDOW_MINUTES as needed for your environment.

Sentry Error Tracking & Monitoring (Optional)

The server optionally supports Sentry for error tracking, performance monitoring, and debugging. Sentry integration is completely optional and only initialized if configured.

Installation

To enable Sentry monitoring, install the optional dependency:

# Using UV (recommended)uv sync --extra sentry

Configuration

Enable Sentry by setting the SENTRY_DSN environment variable in your .env file:

# Required: Sentry DSN for your projectSENTRY_DSN=https://[email protected]/6789
# Optional: Performance monitoring sample rate (0.0-1.0, default: 1.0)SENTRY_TRACES_SAMPLE_RATE=1.0
# Optional: Include personally identifiable information (default: false).# When true, tool inputs and outputs (NetBox inventory data) are sent to Sentry.SENTRY_SEND_DEFAULT_PII=false
# Optional: Environment name (e.g., "production", "staging")SENTRY_ENVIRONMENT=production
# Optional: Release version (auto-detected from package if not set)SENTRY_RELEASE=1.2.3
# Optional: Profiling - continuous profiling sample rate (0.0-1.0, default: 1.0)SENTRY_PROFILE_SESSION_SAMPLE_RATE=1.0
# Optional: Profiling - lifecycle mode for profiling (default: "trace")# Options: "all", "continuation", "trace"SENTRY_PROFILE_LIFECYCLE=trace
# Optional: Enable log capture as breadcrumbs and events (default: true)SENTRY_ENABLE_LOGS=true

Features

When enabled, Sentry automatically captures:

• Exceptions & Errors: All unhandled exceptions with full context
• Performance Metrics: Request/response times and traces
• MCP Integration: Detailed MCP server activity and interactions
• Logs & Breadcrumbs: Application logs and event trails for debugging
• Context Data: Environment, client info, and request parameters

Getting a Sentry DSN

1. Create a free account at sentry.io
2. Create a new Python project
3. Copy your DSN from the project settings
4. Set it in your .env file

Disabling Sentry

Sentry is completely optional. If you don't set SENTRY_DSN, the server will run normally without any Sentry integration, and no monitoring data will be collected.

SSL/TLS Configuration

The server supports SSL certificate verification and custom timeout settings:

NETBOX_VERIFY_SSL=true    # Enable SSL certificate verificationNETBOX_TIMEOUT=30         # Total time per request, retries included (seconds)

Certificates are verified against the operating system trust store, so a NetBox behind an internal CA works as soon as that CA is trusted by the OS. SSL_CERT_FILE or SSL_CERT_DIR take precedence when set.

Transport Configuration

The server supports multiple transport mechanisms for the MCP protocol:

STDIO Transport (Default)

The default transport uses standard input/output for communication. This is ideal for local usage and integration with tools that communicate via stdin/stdout:

MCP_TRANSPORT=stdio

HTTP SSE Transport (Server-Sent Events)

For network-based deployments, you can use HTTP with Server-Sent Events. This allows the MCP server to be accessed over HTTP with real-time streaming:

MCP_TRANSPORT=sseMCP_HTTP_HOST=127.0.0.1        # LocalhostMCP_HTTP_PORT=8000           # Port to listen onMCP_HTTP_BEARER_TOKEN=your-secret-token  # Optional authentication token

When using SSE transport with a bearer token, clients must include the token in their requests:

curl -H "Authorization: Bearer your-secret-token" http://localhost:8000/sse

HTTP Streamable Transport

The HTTP Streamable transport provides HTTP-based communication with request/response streaming. This is ideal for web integrations and tools that need HTTP endpoints:

MCP_TRANSPORT=httpMCP_HTTP_HOST=127.0.0.1        # LocalhostMCP_HTTP_PORT=8000           # Port to listen onMCP_HTTP_BEARER_TOKEN=your-secret-token  # Optional authentication token

When using streamable transport with a bearer token:

curl -H "Authorization: Bearer your-secret-token" \     -H "Accept: application/json, text/event-stream" \     -H "Content-Type: application/json" \     -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' \     http://localhost:8000/mcp

Per-user NetBox tokens

By default every client shares the server's NETBOX_TOKEN, so NetBox sees one user. With NETBOX_TOKEN_PASSTHROUGH=true, each client sends its own NetBox API token instead. NetBox applies that user's permissions and the changelog records the real user:

MCP_TRANSPORT=httpMCP_HTTP_HOST=0.0.0.0NETBOX_TOKEN_PASSTHROUGH=true

claude mcp add --transport http netbox https://netbox-mcp.example.com/mcp \  --header "Authorization: Bearer nbt_your-key.your-token"

• Requests without a token, or with a token NetBox rejects, get HTTP 401. If NetBox cannot be reached to check a token within 10 seconds (or NETBOX_TIMEOUT, if lower), the request gets HTTP 503 with Retry-After, so clients retry instead of logging in again. The 503 passes on NetBox's own Retry-After when NetBox sends one. Accepted tokens are cached for 60 seconds. After that, the token is still accepted right away for up to 10 minutes while the server re-checks it with NetBox in the background, so a known user never waits on a check, even during a NetBox outage. A revoked token is dropped once its re-check comes back; until then it only reaches tools that don't call NetBox (such as the tool list), because NetBox refuses the token on every call that does. Rejected tokens are cached for 30 seconds, so a token just created in NetBox may be refused for up to 30 seconds if it was tried before it existed. At most 8 token checks reach NetBox at once; requests with a token the server hasn't seen yet wait for a free slot, and get HTTP 503 if the wait exceeds the check timeout.
• v2 (nbt_...) and legacy v1 tokens both work; the server sends each to NetBox with the right scheme.
• NETBOX_TOKEN is ignored. Only the http and sse transports are supported, and the server refuses to start if MCP_HTTP_BEARER_TOKEN is set too, since both use the Authorization header.
• With RATE_LIMIT_ENABLED=true, each NetBox user gets their own rate-limit window (each token on NetBox before 4.5), so the limit no longer caps the server's total load on NetBox.
• With NETBOX_PLUGIN_DISCOVERY=true, plugin types found with any user's token are added to one shared list. rediscover replaces that list with what the calling user can see, which drops uninstalled plugins; another user's call that names a type only they can see rediscovers it with their token.
• Clients send their NetBox tokens to this server, so put it behind HTTPS.

Note: The HTTP transport requires proper JSON-RPC formatting with jsonrpc and id fields. The server may also require session initialization for some operations.

Health Endpoint

Both HTTP transports (sse and http) serve GET /health, which answers 200 ok when the server is handling requests. It needs no bearer token and does not contact NetBox, so a NetBox outage does not mark the MCP server unhealthy. The Docker image's HEALTHCHECK uses it:

curl http://localhost:8000/health

For more information on FastMCP transports, see the FastMCP documentation.

🤝 Contributing

Contributions are welcome. See CONTRIBUTING.md for the dev setup, checks and commit message format, and use the issue templates for bugs and feature requests.

Found a security problem? Please report it privately as described in SECURITY.md.

📜 License

MIT License - see LICENSE for details.