home / mcp / netbox mcp server

NetBox MCP Server

FastMCP server for read-only NetBox API access with natural language query support

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "chadkunsman-netbox_mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/yourusername/netbox-mcp.git",
        "--with-editable",
        ".",
        "netbox-mcp-server"
      ],
      "env": {
        "DEBUG": "false",
        "LOG_LEVEL": "info",
        "NETBOX_URL": "https://your-netbox.example.com",
        "NETBOX_TOKEN": "your_api_token",
        "NETBOX_SSL_VERIFY": "true"
      }
    }
  }
}

You can access NetBox data through a read‑only MCP server that exposes NetBox API capabilities to AI systems. It lets you ask natural language questions about devices, sites, circuits, IP prefixes, and VLANs, and receive structured results without altering any NetBox data.

How to use

Start the MCP server and connect with an MCP client that speaks the Model Context Protocol. Use natural language prompts to query the NetBox data, such as asking for devices at a specific site, listing circuits by provider, or finding IP prefixes by VRF. The server translates your queries into precise NetBox API calls under the hood and returns structured results suitable for further processing or display. You can combine cross-field criteria to filter results across devices, sites, circuits, prefixes, and VLANs, and use fuzzy matching to locate items when you’re not sure of exact names. If a query can’t be resolved confidently, you’ll receive helpful guidance and suggested refinements.

How to install

# Start the MCP server locally using the recommended runner
uvx --from . \
  --with-editable . \
  --env NETBOX_URL=https://your-netbox.example.com \
  --env NETBOX_TOKEN=your_api_token \
  --env NETBOX_SSL_VERIFY=true \
  netbox-mcp-server

If you are developing or testing, you can clone the project, install dependencies in a development environment, and run the server from source.

# Development setup
git clone https://github.com/yourusername/netbox-mcp.git
cd netbox-mcp

# Create and activate a virtual environment, then install in editable mode
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install -e .

# Set required environment variables
export NETBOX_URL=https://your-netbox.example.com
export NETBOX_TOKEN=your_api_token
export NETBOX_SSL_VERIFY=true

Additional configuration and usage notes

Environment variables control the server’s connection to NetBox and its runtime behavior. You can adjust debugging and logging via common flags. The following variables are used by default:

- NETBOX_URL: URL of your NetBox instance - NETBOX_TOKEN: API token with the necessary permissions - NETBOX_SSL_VERIFY: true to verify SSL certificates, or false to skip verification - DEBUG: enable or disable debug mode - LOG_LEVEL: set the logging level (info, debug, warning, error)

Example testing and client setup

If you want to try out the MCP integration from a client or script, configure the client to connect to the MCP server using its standard MCP endpoint. Use natural language queries to fetch devices, sites, circuits, IP prefixes, and VLANs. Expect structured results that you can present directly to users or feed into other automation steps.

Troubleshooting tips

If you encounter authentication errors, double‑check NETBOX_TOKEN and the NetBox URL. If you see SSL verification failures, confirm NETBOX_SSL_VERIFY is set to true and that your NetBox TLS configuration is valid. For network or permission issues, verify that the API token has the required read permissions for the relevant resources.

Security considerations

Operate the MCP server in a controlled environment with access restricted to trusted clients. Since the server is read-only, it avoids modifying NetBox data, but you should still protect your NetBox API token and ensure transport security (use HTTPS and valid certificates). Review token scopes and rotate credentials periodically.

Notes

This server provides read‑only access to NetBox resources via MCP. It supports querying devices, sites, circuits, IP prefixes, and VLANs with flexible filtering and natural language processing to improve discoverability and usability for AI assistants.

Available tools

devices

Query NetBox devices with filters, search by name, and use natural language to describe device information; supports filtering by site, role, status, manufacturer, and more.

sites

List sites with status and region details; retrieve comprehensive site information including device and rack counts; enable site-based filtering across resources.

circuits

Query circuits by provider, type, status, termination sites; search with natural language; track A-side and Z-side terminations; filter by circuit IDs.

prefixes

Query IP prefixes by site, VRF, tenant, status, and role; handle IPv4/IPv6; filter by VLAN; manage CIDR pools and patterns.

vlans

Query VLANs by name, VID, site, group, tenant, and status; true substring matching for names/descriptions; cross-field search across VLAN properties; supports VLAN groups and tenants.