Skip to main content

NetBox MCP Server

⚠️ Breaking Change in v1.0.0: The project structure has changed. If upgrading from v0.1.0, update your configuration:

  • Change uv run server.py to uv run netbox-mcp-server
  • Update Claude Desktop/Code configs to use netbox-mcp-server instead of server.py
  • Docker users: rebuild images with updated CMD
  • See CHANGELOG.md for full details

This is a simple read-only Model Context Protocol server for NetBox. It enables you to interact with your data in NetBox directly via LLMs that support MCP.

The server is intentionally simple: easy to get started with, hard to misuse (read-only by default, no plugin surface), and easy to fork and adapt. Forking under Apache 2.0 is a first-class path for users who need capabilities beyond the project's scope.

Community

For chat, use cases, and general MCP discussion, join the NetBox community at netdev.chat. The #ai channel is the right home for MCP integrations, questions, and sharing use cases. Bugs and feature ideas specific to this server go in issues.

Tools

Tool Description
netbox_get_objects Retrieves NetBox core objects based on their type and filters
netbox_get_object_by_id Gets detailed information about a specific NetBox object by its ID
netbox_get_changelogs Retrieves change history records (audit trail) based on filters
netbox_search_objects Searches NetBox objects by a text query, optionally limited by object type and returned fields

Note: Core NetBox object types are always available. Plugin object types can be auto-discovered. See Plugin Object Type Discovery. Advanced features (GraphQL, dynamic model discovery, etc.) are deliberately out of scope. See CONTRIBUTING.md for the full scope statement and rationale.

Usage

  1. Create a read-only API token in NetBox with sufficient permissions for the tool to access the data you want to make available via MCP.

  2. Install the server. The published package runs without a clone:

    # Run directly with uv
    uvx netbox-mcp-server
    
    # Or install with pip
    pip install netbox-mcp-server
    

    To run from a clone of this repository instead, install dependencies:

    # Using UV (recommended)
    uv sync
    
    # Or using pip
    pip install -e .
    
  3. Verify the server can run: NETBOX_URL=https://netbox.example.com/ NETBOX_TOKEN=<your-api-token> uv run netbox-mcp-server (from a clone), or the same with uvx netbox-mcp-server for the published package.

  4. Add the MCP server to your LLM client. See below for some examples with Claude.

Claude Code

Stdio Transport (Default)

Add the server using the claude mcp add command:

claude mcp add --transport stdio netbox \
  --env NETBOX_URL=https://netbox.example.com/ \
  --env NETBOX_TOKEN=<your-api-token> \
  -- uv --directory /path/to/netbox-mcp-server run netbox-mcp-server

Important notes:

  • Replace /path/to/netbox-mcp-server with the absolute path to your local clone, or replace everything after -- with uvx netbox-mcp-server to use the published package
  • The -- separator distinguishes Claude Code flags from the server command
  • Use --scope project to share the configuration via .mcp.json in version control
  • Use --scope user to make it available across all your projects (default is local)

After adding, verify with /mcp in Claude Code or claude mcp list in your terminal.

HTTP Transport

For HTTP transport, first start the server manually:

# Start the server with HTTP transport (using .env or environment variables)
NETBOX_URL=https://netbox.example.com/ \
NETBOX_TOKEN=<your-api-token> \
TRANSPORT=http \
uv run netbox-mcp-server

Then add the running server to Claude Code:

# Add the HTTP MCP server (note: URL must include http:// or https:// prefix)
claude mcp add --transport http netbox http://127.0.0.1:8000/mcp

Important notes:

  • The URL must include the protocol prefix (http:// or https://)
  • The default endpoint is /mcp when using HTTP transport
  • The server must be running before Claude Code can connect
  • Verify the connection with claude mcp list - you should see a ✓ next to the server name

Claude Desktop

Add the server configuration to your Claude Desktop config file. On Mac, edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
    "mcpServers": {
        "netbox": {
            "command": "uv",
            "args": [
                "--directory",
                "/path/to/netbox-mcp-server",
                "run",
                "netbox-mcp-server"
            ],
            "env": {
                "NETBOX_URL": "https://netbox.example.com/",
                "NETBOX_TOKEN": "<your-api-token>"
            }
        }
    }
}

On Windows, use full, escaped path to your instance, such as C:\\Users\\myuser\\.local\\bin\\uv and C:\\Users\\myuser\\netbox-mcp-server. For detailed troubleshooting, consult the MCP quickstart.

  1. Use the tools in your LLM client. For example:
> Get all devices in the 'Equinix DC14' site
...
> Tell me about my IPAM utilization
...
> What Cisco devices are in my network?
...
> Who made changes to the NYC site in the last week?
...
> Show me all configuration changes to the core router in the last month

Field Filtering (Token Optimization)

Both netbox_get_objects() and netbox_get_object_by_id() support an optional fields parameter to reduce token usage:

# Without fields: ~5000 tokens for 50 devices
devices = netbox_get_objects("devices", {"site": "datacenter-1"})

# With fields: ~500 tokens (90% reduction)
devices = netbox_get_objects(
    "devices", {"site": "datacenter-1"}, fields=["id", "name", "status", "site"]
)

Common field patterns:

  • Devices: ['id', 'name', 'status', 'device_type', 'site', 'primary_ip4']
  • IP Addresses: ['id', 'address', 'status', 'dns_name', 'description']
  • Interfaces: ['id', 'name', 'type', 'enabled', 'device']
  • Sites: ['id', 'name', 'status', 'region', 'description']

The fields parameter uses NetBox's native field filtering. See the NetBox API documentation for details.

Configuration

The server supports multiple configuration sources with the following precedence (highest to lowest):

  1. Command-line arguments (highest priority)
  2. Environment variables
  3. .env file in the project root
  4. Default values (lowest priority)

Configuration Reference

Setting Type Default Required Description
NETBOX_URL URL - Yes Base URL of your NetBox instance (e.g., https://netbox.example.com/)
NETBOX_TOKEN String - Unless TOKEN_PASSTHROUGH API token for authentication. Must not be set with TOKEN_PASSTHROUGH.
TRANSPORT stdio | http stdio No MCP transport protocol
HOST String 127.0.0.1 If HTTP Host address for HTTP server
PORT Integer 8000 If HTTP Port for HTTP server
MCP_AUTH_TOKEN String - No Bearer token required on the HTTP endpoint. When unset, the HTTP transport is unauthenticated. Clients send Authorization: Bearer <token>.
TOKEN_PASSTHROUGH Boolean false No HTTP only. Each client sends its own NetBox token and NetBox applies that user's permissions. See Per-User NetBox Tokens.
VERIFY_SSL Boolean true No Whether to verify SSL certificates
ENABLE_PLUGIN_DISCOVERY Boolean false No Auto-discover plugin object types at startup
LOG_LEVEL DEBUG | INFO | WARNING | ERROR | CRITICAL INFO No Logging verbosity

Transport Examples

Stdio Transport (Claude Desktop/Code)

For local Claude Desktop or Claude Code usage with stdio transport:

{
    "mcpServers": {
        "netbox": {
            "command": "uv",
            "args": ["--directory", "/path/to/netbox-mcp-server", "run", "netbox-mcp-server"],
            "env": {
                "NETBOX_URL": "https://netbox.example.com/",
                "NETBOX_TOKEN": "<your-api-token>"
            }
        }
    }
}

HTTP Transport (Web Clients)

For web-based MCP clients using HTTP/SSE transport:

# Using environment variables
export NETBOX_URL=https://netbox.example.com/
export NETBOX_TOKEN=<your-api-token>
export TRANSPORT=http
export HOST=127.0.0.1
export PORT=8000

uv run netbox-mcp-server

# Or using CLI arguments
uv run netbox-mcp-server \
  --netbox-url https://netbox.example.com/ \
  --netbox-token <your-api-token> \
  --transport http \
  --host 127.0.0.1 \
  --port 8000

Per-User NetBox Tokens (Token Passthrough)

By default every client shares the permissions of NETBOX_TOKEN. With TOKEN_PASSTHROUGH=true, each client sends its own NetBox API token instead, and the server makes every NetBox call with that token. NetBox then applies that user's object permissions, so two people using the same server only see what they could see in NetBox itself.

export NETBOX_URL=https://netbox.example.com/
export TRANSPORT=http
export TOKEN_PASSTHROUGH=true
# NETBOX_TOKEN must not be set

uv run netbox-mcp-server

Each user creates an API token in NetBox (read-only is enough) and adds it to their client. Send it as Bearer even for v1 tokens; the server uses the right scheme towards NetBox.

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

How it works:

  • The server checks each bearer against NetBox (/api/authentication-check/, or /api/users/config/ on NetBox < 4.5). A token NetBox rejects (invalid, disabled, expired, or not allowed from this IP) gets 401. If NetBox cannot be reached or fails, the client gets 503 with Retry-After, not a misleading 401.
  • Accepted tokens are remembered for 60 seconds. A token revoked in that window still gets no data, because NetBox rejects the tool calls made with it.
  • An MCP session belongs to the user who opened it; another user's token cannot use it.
  • Tokens are kept in memory only (hashed as cache keys) and are never logged.
  • Clients send their NetBox token to this server, so always put it behind TLS. The server also forwards those tokens to NetBox, and logs a warning at startup if NETBOX_URL is plain HTTP (other than localhost) or VERIFY_SSL is off.

Limitations:

  • MCP_AUTH_TOKEN and ENABLE_PLUGIN_DISCOVERY cannot be combined with this mode, since both rely on a shared token. Plugin object types are not available.
  • Clients must be able to send a static Authorization header. MCP clients that only support OAuth sign-in cannot use this mode.
  • Each request with an unknown token costs one NetBox API call, so rate-limit this server at your proxy if it is exposed widely.
  • NetBox checks a token's Allowed IPs against the address that connects to it, which is this server, not the user. Tokens with Allowed IPs only work if the allowed range includes this server.

Example .env File

Create a .env file in the project root:

# Core NetBox Configuration
NETBOX_URL=https://netbox.example.com/
NETBOX_TOKEN=your_api_token_here

# Transport Configuration (optional, defaults to stdio)
TRANSPORT=stdio

# HTTP Transport Settings (only used if TRANSPORT=http)
# HOST=127.0.0.1
# PORT=8000
# Bearer token required on the HTTP endpoint. When unset, the endpoint is unauthenticated.
# MCP_AUTH_TOKEN=a-strong-random-token
# Use each client's own NetBox token instead of NETBOX_TOKEN (HTTP only)
# TOKEN_PASSTHROUGH=true

# Security (optional, defaults to true)
VERIFY_SSL=true

# Plugin Discovery (optional, defaults to false)
# ENABLE_PLUGIN_DISCOVERY=true

# Logging (optional, defaults to INFO)
LOG_LEVEL=INFO

CLI Arguments

All configuration options can be overridden via CLI arguments:

uv run netbox-mcp-server --help

# Common examples:
uv run netbox-mcp-server --log-level DEBUG --no-verify-ssl  # Development
uv run netbox-mcp-server --transport http --port 9000       # Custom HTTP port

Docker Usage

Pre-built Image (Docker Hub)

Pre-built multi-arch images (linux/amd64, linux/arm64) are published to Docker Hub on every tagged release:

docker pull netboxlabs/netbox-mcp-server:latest

Pin to a specific version in production. The latest tag tracks the most recent release and can change without notice. See the releases page for available versions:

docker pull netboxlabs/netbox-mcp-server:<X.Y.Z>   # exact version
docker pull netboxlabs/netbox-mcp-server:<X.Y>     # latest within a minor
docker pull netboxlabs/netbox-mcp-server:<X>       # latest within a major

Verify image provenance (optional but recommended). Images are signed with cosign (keyless, via GitHub OIDC) and ship with SLSA build provenance:

cosign verify \
  --certificate-identity-regexp '^https://github.com/netboxlabs/netbox-mcp-server/' \
  --certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \
  netboxlabs/netbox-mcp-server:<tag>

Standard Docker Image

Build and run the NetBox MCP server in a container:

# Build the image
docker build -t netbox-mcp-server:latest .

# Run with HTTP transport (required for Docker containers)
docker run --rm \
  -e NETBOX_URL=https://netbox.example.com/ \
  -e NETBOX_TOKEN=<your-api-token> \
  -e TRANSPORT=http \
  -e HOST=0.0.0.0 \
  -e PORT=8000 \
  -e MCP_AUTH_TOKEN=<a-strong-random-token> \
  -p 8000:8000 \
  netbox-mcp-server:latest

Note: Docker containers require TRANSPORT=http since stdio transport doesn't work in containerized environments.

⚠️ Security: The HTTP transport has no authentication unless you set MCP_AUTH_TOKEN or use token passthrough. Binding to HOST=0.0.0.0 exposes read access to all NetBox data your token can see to anyone who can reach the port. Set a strong MCP_AUTH_TOKEN (clients then send Authorization: Bearer <token>) and terminate TLS at a reverse proxy or gateway before exposing the server to a network. A bearer token sent over plain HTTP can be intercepted, so TLS is required for real deployments.

Connecting to NetBox on your host machine:

If your NetBox instance is running on your host machine (not in a container), you need to use host.docker.internal instead of localhost on macOS and Windows:

# For NetBox running on host (macOS/Windows)
docker run --rm \
  -e NETBOX_URL=http://host.docker.internal:18000/ \
  -e NETBOX_TOKEN=<your-api-token> \
  -e TRANSPORT=http \
  -e HOST=0.0.0.0 \
  -e PORT=8000 \
  -e MCP_AUTH_TOKEN=<a-strong-random-token> \
  -p 8000:8000 \
  netbox-mcp-server:latest

Note: On Linux, you can use --network host instead, or use the host's IP address directly.

With additional configuration options:

docker run --rm \
  -e NETBOX_URL=https://netbox.example.com/ \
  -e NETBOX_TOKEN=<your-api-token> \
  -e TRANSPORT=http \
  -e HOST=0.0.0.0 \
  -e MCP_AUTH_TOKEN=<a-strong-random-token> \
  -e LOG_LEVEL=DEBUG \
  -e VERIFY_SSL=false \
  -p 8000:8000 \
  netbox-mcp-server:latest

With per-user NetBox tokens (token passthrough):

docker run --rm \
  -e NETBOX_URL=https://netbox.example.com/ \
  -e TRANSPORT=http \
  -e HOST=0.0.0.0 \
  -e TOKEN_PASSTHROUGH=true \
  -p 8000:8000 \
  netbox-mcp-server:latest

Leave out NETBOX_TOKEN and MCP_AUTH_TOKEN; each client sends its own NetBox token.

The server will be accessible at http://localhost:8000/mcp for MCP clients. You can connect to it using your preferred method.

Plugin Object Type Discovery

By default, only core NetBox object types are available. If your NetBox instance has plugins installed (e.g., netbox-dns, netbox-inventory), you can enable automatic discovery to make their object types available as well.

Enabling Discovery

Set the ENABLE_PLUGIN_DISCOVERY environment variable or use the --enable-plugin-discovery CLI flag:

# Via environment variable
ENABLE_PLUGIN_DISCOVERY=true uv run netbox-mcp-server

# Via CLI flag
uv run netbox-mcp-server --enable-plugin-discovery

# In Claude Desktop config
{
    "mcpServers": {
        "netbox": {
            "command": "uv",
            "args": ["--directory", "/path/to/netbox-mcp-server", "run", "netbox-mcp-server"],
            "env": {
                "NETBOX_URL": "https://netbox.example.com/",
                "NETBOX_TOKEN": "<your-api-token>",
                "ENABLE_PLUGIN_DISCOVERY": "true"
            }
        }
    }
}

How It Works

At startup, the server queries NetBox's core/object-types API endpoint (with extras/object-types fallback for NetBox < 4.4) to find all installed plugin models that have REST API endpoints. These are merged into the runtime type registry alongside the core types.

Discovered plugin types use the app_label.model naming convention (e.g., netbox_dns.zone, netbox_inventory.asset) and work with all existing tools (netbox_get_objects, netbox_get_object_by_id, netbox_search_objects).

Requirements

  • NetBox 4.2 or later
  • API token must have read access to the object-types endpoint
  • Plugin models must expose a REST API endpoint to be discovered

Failure Behavior

If discovery fails for any reason (network error, insufficient permissions, unsupported NetBox version), the server logs a warning and continues with core types only. This ensures the server always starts successfully regardless of discovery outcome.

Development

Contributions are welcome! Please read CONTRIBUTING.md before proposing new features. We encourage filing an issue for discussion first to confirm scope fit.

If your use case needs capabilities outside this project's scope, forking under Apache 2.0 is an actively supported path.

License

This project is licensed under the Apache 2.0 license. See the LICENSE file for details.

Metadata

Release files for netbox-mcp-server 1.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for netbox-mcp-server 1.3.0
File Size Uploaded Provenance Actions
netbox_mcp_server-1.3.0.tar.gz 53.5 kB With provenance Details for netbox_mcp_server-1.3.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for netbox-mcp-server 1.3.0
File Interpreter ABI Platform Actions
netbox_mcp_server-1.3.0-py3-none-any.whl Python 3 none any Details for netbox_mcp_server-1.3.0-py3-none-any.whl

Total release size: 85.3 kB

Release files / netbox_mcp_server-1.3.0.tar.gz

Download URL netbox_mcp_server-1.3.0.tar.gz
Size 53.5 kB
Tags Source
SHA-256 checksum
How to use checksums
157e37d350475c218b9e400a380ca41e4094982f454ace1277bc5d78393fdc30
BLAKE2b-256 checksum
How to use checksums
a7d3480eaa4c2cf1383eab8f96be980ae6c5a5e1accfcfbf1e03ab39601c0637
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.

Transparency log

Release files / netbox_mcp_server-1.3.0-py3-none-any.whl

Download URL netbox_mcp_server-1.3.0-py3-none-any.whl
Size 31.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
309cb138f59d197513e86f801ac4afd7ad41915cd3a24504aa0b4cc5cde22de1
BLAKE2b-256 checksum
How to use checksums
ae5e7945c611395e05b526912a28b91b783d9c9966ececc70ac08c4e3e9dfa19
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.

Transparency log

Security for netbox-mcp-server 1.3.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for netbox_mcp_server-1.3.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.3.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page