Skip to main content
Glama
netboxlabs

NetBox MCP Server

Official
by netboxlabs
OverviewSchemaRelated ServersScoreDiscussions
Python
Hybrid

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.

Related MCP server: NetBox MCP Server

Tools

Tool

Description

get_objects

Retrieves NetBox core objects based on their type and filters

get_object_by_id

Gets detailed information about a specific NetBox object by its ID

get_changelogs

Retrieves change history records (audit trail) based on filters

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

  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

  • 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

-

Yes

API token for authentication

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

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

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

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

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.

Available Tools

4 tools
netbox_get_changelogsB

Get object change records (changelogs) from NetBox based on filters.

ParametersJSON Schema
NameRequiredDescriptionDefault
filtersYesdict of filters to apply to the API call based on the NetBox API filtering options

TDQS

B3.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must disclose behavioral traits. It mentions filtering but does not describe pagination, return format, or whether the operation is read-only. The lack of detail reduces transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, clear sentence with no extraneous words. It efficiently conveys the core purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the lack of output schema and annotations, the description is too sparse. It does not explain return values, pagination behavior, or possible filter options, making it incomplete for effective tool use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Although schema coverage is 100%, the description adds no value beyond the schema's generic 'dict of filters' explanation. It does not specify acceptable filter keys or semantics, leaving the agent guessing.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Get' and the resource 'object change records (changelogs)', which is specific and distinguishes from sibling tools like 'netbox_get_objects' and 'netbox_get_object_by_id'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives; it only states the action without context about filtering or scenarios where changelogs are needed.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

netbox_get_object_by_idB

Get detailed information about a specific NetBox object by its ID.

ParametersJSON Schema
NameRequiredDescriptionDefault
briefNoreturns only a minimal representation of the object in the response. This is useful when you need only a summary of the object without any related data.
fieldsNoOptional list of specific fields to return **IMPORTANT: ALWAYS USE THIS PARAMETER TO MINIMIZE TOKEN USAGE** Field filtering reduces response payload by 80-90% and is critical for performance. - None or [] = returns all fields (NOT RECOMMENDED - use only when you need complete objects) - ['id', 'name'] = returns only specified fields (RECOMMENDED) Examples: - For basic info: ['id', 'name', 'status'] - For devices: ['id', 'name', 'status', 'site'] - For IP addresses: ['address', 'dns_name', 'vrf', 'status'] Uses NetBox's native field filtering via ?fields= parameter. **Always specify only the fields you actually need.**
object_idYesThe numeric ID of the object
object_typeYesString representing the NetBox object type (e.g. "dcim.device", "ipam.ipaddress")

TDQS

B3.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Without annotations, the description carries the full burden of behavioral disclosure. It merely states 'get detailed information' without describing what that entails, such as the structure of the response, authentication requirements, or error handling. This is insufficient.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise, consisting of a single sentence with no extraneous words. It efficiently conveys the core purpose without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has four parameters, no output schema, and no annotations, the description is too minimal. It does not explain what 'detailed information' includes, mention pagination, or address potential errors. More context is needed for adequate completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already fully documents all four parameters. The description adds no additional meaning beyond what is in the schema. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly identifies the operation as getting detailed information about a specific NetBox object by ID, using a specific verb and resource. It distinguishes this from sibling tools like netbox_get_objects (plural, not by ID) and netbox_search_objects (search vs. retrieval).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus its siblings. It does not mention that it is intended for fetching a single object by ID, while netbox_get_objects might retrieve multiple objects. No exclusion criteria or alternatives are given.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

netbox_get_objectsA
Get objects from NetBox based on their type and filters

Args:
    object_type: String representing the NetBox object type (e.g. "dcim.device", "ipam.ipaddress")
    filters: dict of filters to apply to the API call based on the NetBox API filtering options

            FILTER RULES:
            Valid: Direct fields like {'site_id': 1, 'name': 'router', 'status': 'active'}
            Valid: Field-supported lookups like {'name__ic': 'switch', 'vid__gte': 100}
            Invalid: Multi-hop like {'device__site_id': 1} - NOT supported

            Lookup suffixes: n, ic, nic, isw, nisw, iew, niew, ie, nie,
                             empty, regex, iregex, lt, lte, gt, gte
            Lookup support is field-specific. NetBox may silently ignore unsupported
            lookups and return overly broad results. The '__in' suffix is not supported
            and is rejected by this tool. For multiple values, pass a list as the field
            value directly: {'vminterface_id': [621493, 631527]} or {'id': [1, 2, 3]}.

            Two-step pattern for cross-relationship queries:
              sites = netbox_get_objects('dcim.site', {'name': 'NYC'})
              netbox_get_objects('dcim.device', {'site_id': sites[0]['id']})

    fields: Optional list of specific fields to return
            **IMPORTANT: ALWAYS USE THIS PARAMETER TO MINIMIZE TOKEN USAGE**
            Field filtering significantly reduces response payload and is critical for performance.

            - None or [] = returns all fields (NOT RECOMMENDED - use only when you need complete objects)
            - ['id', 'name'] = returns only specified fields (RECOMMENDED)

            Examples:
            - For counting: ['id'] (minimal payload)
            - For listings: ['id', 'name', 'status']
            - For IP addresses: ['address', 'dns_name', 'description']

            Uses NetBox's native field filtering via ?fields= parameter.
            **Always specify only the fields you actually need.**

    brief: returns only a minimal representation of each object in the response.
           This is useful when you need only a list of available objects without any related data.

    limit: Maximum results to return (default 5, max 100)
           Start with default, increase only if needed

    offset: Skip this many results for pagination (default 0)
            Example: offset=0 (page 1), offset=5 (page 2), offset=10 (page 3)

    ordering: Fields used to determine sort order of results.
              Field names may be prefixed with '-' to invert the sort order.
              Multiple fields may be specified with a list of strings.

              Examples:
              - 'name' (alphabetical by name)
              - '-id' (ordered by ID descending)
              - ['facility', '-name'] (by facility, then by name descending)
              - None, '' or [] (default NetBox ordering)


Returns:
    Paginated response dict with the following structure:
        - count: Total number of objects matching the query
                 ALWAYS REFER TO THIS FIELD FOR THE TOTAL NUMBER OF OBJECTS MATCHING THE QUERY
        - next: URL to next page (or null if no more pages)
                ALWAYS REFER TO THIS FIELD FOR THE NEXT PAGE OF RESULTS
        - previous: URL to previous page (or null if on first page)
                    ALWAYS REFER TO THIS FIELD FOR THE PREVIOUS PAGE OF RESULTS
        - results: Array of objects for this page
                   ALWAYS REFER TO THIS FIELD FOR THE OBJECTS ON THIS PAGE

ENSURE YOU ARE AWARE THE RESULTS ARE PAGINATED BEFORE PROVIDING RESPONSE TO THE USER.

Valid object_type values:

- circuits.circuit

  • circuits.circuitgroup

  • circuits.circuitgroupassignment

  • circuits.circuittermination

  • circuits.circuittype

  • circuits.provider

  • circuits.provideraccount

  • circuits.providernetwork

  • circuits.virtualcircuit

  • circuits.virtualcircuittermination

  • circuits.virtualcircuittype

  • core.datafile

  • core.datasource

  • core.job

  • core.objectchange

  • core.objecttype

  • dcim.cable

  • dcim.cabletermination

  • dcim.consoleport

  • dcim.consoleporttemplate

  • dcim.consoleserverport

  • dcim.consoleserverporttemplate

  • dcim.device

  • dcim.devicebay

  • dcim.devicebaytemplate

  • dcim.devicerole

  • dcim.devicetype

  • dcim.frontport

  • dcim.frontporttemplate

  • dcim.interface

  • dcim.interfacetemplate

  • dcim.inventoryitem

  • dcim.inventoryitemrole

  • dcim.inventoryitemtemplate

  • dcim.location

  • dcim.macaddress

  • dcim.manufacturer

  • dcim.module

  • dcim.modulebay

  • dcim.modulebaytemplate

  • dcim.moduletype

  • dcim.moduletypeprofile

  • dcim.platform

  • dcim.powerfeed

  • dcim.poweroutlet

  • dcim.poweroutlettemplate

  • dcim.powerpanel

  • dcim.powerport

  • dcim.powerporttemplate

  • dcim.rack

  • dcim.rackreservation

  • dcim.rackrole

  • dcim.racktype

  • dcim.rearport

  • dcim.rearporttemplate

  • dcim.region

  • dcim.site

  • dcim.sitegroup

  • dcim.virtualchassis

  • dcim.virtualdevicecontext

  • extras.bookmark

  • extras.configcontext

  • extras.configcontextprofile

  • extras.configtemplate

  • extras.customfield

  • extras.customfieldchoiceset

  • extras.customlink

  • extras.eventrule

  • extras.exporttemplate

  • extras.imageattachment

  • extras.journalentry

  • extras.notification

  • extras.notificationgroup

  • extras.savedfilter

  • extras.script

  • extras.subscription

  • extras.tableconfig

  • extras.tag

  • extras.taggeditem

  • extras.webhook

  • ipam.aggregate

  • ipam.asn

  • ipam.asnrange

  • ipam.fhrpgroup

  • ipam.fhrpgroupassignment

  • ipam.ipaddress

  • ipam.iprange

  • ipam.prefix

  • ipam.rir

  • ipam.role

  • ipam.routetarget

  • ipam.service

  • ipam.servicetemplate

  • ipam.vlan

  • ipam.vlangroup

  • ipam.vlantranslationpolicy

  • ipam.vlantranslationrule

  • ipam.vrf

  • tenancy.contact

  • tenancy.contactassignment

  • tenancy.contactgroup

  • tenancy.contactrole

  • tenancy.tenant

  • tenancy.tenantgroup

  • users.group

  • users.objectpermission

  • users.owner

  • users.ownergroup

  • users.token

  • users.user

  • virtualization.cluster

  • virtualization.clustergroup

  • virtualization.clustertype

  • virtualization.virtualdisk

  • virtualization.virtualmachine

  • virtualization.vminterface

  • vpn.ikepolicy

  • vpn.ikeproposal

  • vpn.ipsecpolicy

  • vpn.ipsecprofile

  • vpn.ipsecproposal

  • vpn.l2vpn

  • vpn.l2vpntermination

  • vpn.tunnel

  • vpn.tunnelgroup

  • vpn.tunneltermination

  • wireless.wirelesslan

  • wireless.wirelesslangroup

  • wireless.wirelesslink

    See NetBox API documentation for filtering options for each object type.

ParametersJSON Schema
NameRequiredDescriptionDefault
briefNo
limitNo
fieldsNo
offsetNo
filtersYes
orderingNo
object_typeYes

TDQS

A4.9/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description fully discloses behavior: it's a read operation returning paginated results, with default limit=5 and max=100. It warns about unsupported lookups being silently ignored, explains field filtering, and details the return structure (count, next, previous, results). The note about pagination is critical.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured (Args, Returns, lists) and front-loaded with the core purpose. However, it is verbose, especially the long list of valid object_type values and repeated capitalization of 'ALWAYS REFER'. While comprehensive, it could be more concise without losing clarity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (7 parameters, no output schema, no annotations), the description is remarkably complete. It covers every parameter, pagination, return structure, filter rules, and common pitfalls. Sibling tools exist but the description alone sufficiently defines the tool's domain.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, but the description compensates thoroughly by explaining each of the 7 parameters: object_type (with full list), filters (rules, lookups, examples), fields (importance, examples), brief, limit, offset, ordering (syntax, examples). It adds significant meaning beyond the bare schema types and constraints.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Get objects from NetBox based on their type and filters.' It uses a specific verb-resource pair, distinguishes from siblings like netbox_get_object_by_id (single object) and netbox_search_objects, and includes the scope of operation (listing/filtering).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides extensive usage guidelines: valid filter rules (direct fields, lookups), unsupported patterns (multi-hop, '__in'), two-step cross-relationship pattern, mandatory use of 'fields' parameter, pagination with limit/offset, ordering examples. It implicitly instructs when not to use this tool (e.g., for single objects, use get_object_by_id). Clear and actionable.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

netbox_search_objectsA
Perform global search across NetBox infrastructure.

Searches names, descriptions, IP addresses, serial numbers, asset tags,
and other key fields across multiple object types.

Args:
    query: Search term (device names, IPs, serial numbers, hostnames, site names)
           Examples: 'switch01', '192.168.1.1', 'NYC-DC1', 'SN123456'
    object_types: Limit search to specific types (optional)
                 Default: [dcim.device', 'dcim.site', 'ipam.ipaddress', 'dcim.interface', 'dcim.rack', 'ipam.vlan', 'circuits.circuit', 'virtualization.virtualmachine]
                 Examples: ['dcim.device', 'ipam.ipaddress', 'dcim.site']
    fields: Optional list of specific fields to return (reduces response size) IT IS STRONGLY RECOMMENDED TO USE THIS PARAMETER TO MINIMIZE TOKEN USAGE.
            - None or [] = returns all fields (no filtering)
            - ['id', 'name'] = returns only specified fields
            Examples: ['id', 'name', 'status'], ['address', 'dns_name']
            Uses NetBox's native field filtering via ?fields= parameter
    limit: Max results per object type (default 5, max 100)

Returns:
    Dictionary with object_type keys and list of matching objects.
    All searched types present in result (empty list if no matches).

Example:
    # Search for anything matching "switch"
    results = netbox_search_objects('switch')
    # Returns: {
    #   'dcim.device': [{'id': 1, 'name': 'switch-01', ...}],
    #   'dcim.site': [],
    #   ...
    # }

    # Search for IP address
    results = netbox_search_objects('192.168.1.100')
    # Returns: {
    #   'ipam.ipaddress': [{'id': 42, 'address': '192.168.1.100/24', ...}],
    #   ...
    # }

    # Limit search to specific types with field projection
    results = netbox_search_objects(
        'NYC',
        object_types=['dcim.site', 'dcim.location'],
        fields=['id', 'name', 'status']
    )
ParametersJSON Schema
NameRequiredDescriptionDefault
limitNo
queryYes
fieldsNo
object_typesNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.6/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description bears full burden. It fully discloses behavior: returns a dictionary with object_type keys, limits per type (default 5, max 100), supports field filtering, and explains the result structure (empty lists for types with no matches). No contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is quite long, spanning several paragraphs with multiple examples. While well-structured with Args, Returns, and Examples sections, it is not concise. The length is justified by the wealth of information, but it could be trimmed slightly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (4 parameters, output schema exists), the description is very complete. It covers search scope, all parameters with details, return format, and multiple examples. There are no apparent gaps in informing the AI agent about how to use the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, but the description compensates thoroughly. Each parameter is explained with examples: 'query' with sample search terms, 'object_types' with default list and examples, 'fields' with recommendation and examples, 'limit' with default and max. This adds significant meaning beyond the bare schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Perform global search across NetBox infrastructure' and lists the fields searched (names, descriptions, IPs, etc.). This distinguishes it from sibling tools like netbox_get_object_by_id (single object retrieval) and netbox_get_objects (likely list/retrieve without search), making the purpose unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides extensive guidance: when to use (global search), detailed parameter explanations, examples for various search terms, and a strong recommendation to use the 'fields' parameter to minimize token usage. However, it does not explicitly state when not to use this tool or compare directly with siblings within the description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 4 tool updatesv1.2.1
    • First observednetbox_get_changelogs
    • First observednetbox_get_object_by_id
    • First observednetbox_get_objects
    • First observednetbox_search_objects
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.6/5.0
Disambiguation5/5

Each tool has a clearly distinct purpose: changelogs, single-object by ID, filtered listing with pagination, and global cross-type search. No overlap in functionality.

Naming Consistency4/5

Three tools follow 'netbox_get_<object>' pattern, but 'netbox_search_objects' uses 'search' instead of 'get', causing minor inconsistency. Overall pattern is clear and predictable.

Tool Count3/5

With 4 tools for a large domain like NetBox, the set feels slightly under-scoped. While the tools are generic and powerful, typical MCP servers for similar domains have 5-15 tools.

Completeness2/5

The server only supports read operations (get, search, changelogs). Missing create, update, and delete capabilities, which are essential for managing NetBox resources. This is a significant gap for most use cases.

Maintenance

ActivityStale
ResponsivenessUnresponsive

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/netboxlabs/netbox-mcp-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server