mcp-netbox

MCP server to query and edit NetBox over stdio.

Environment Variables

Variable	Description
NETBOX_URL	NetBox URL (default: https://netbox.simoncor.net)
NETBOX_TOKEN	NetBox API token (required)
NETBOX_READ_ONLY	Set to true to turn the write tools off

The token is sent as Bearer for v2 tokens (nbt_<key>.<secret>) and as Token for legacy v1 tokens. The write tools need a token with write access, without it NetBox refuses them. NETBOX_READ_ONLY blocks them in the server as well.

Tools

Tool	Description
get_status	NetBox version, plugins and worker status
list_object_types	List the object types (dcim.devices, ...)
list_objects	List objects of a type, with API filters
get_object	Get one object by ID
search	Search text across several object types at once
get_changelog	Recent changes: who changed what and when
create_objects	Create one object or a batch (all or none)
update_object	Change fields of one object
update_objects	Change fields of several objects (all or none)
delete_object	Delete one object
delete_objects	Delete several objects (all or none)

Object types are written as app.endpoint, for example dcim.devices or ipam.ip-addresses. list_object_types shows what the instance offers.

Filters and tokens

list_objects takes the normal NetBox API filters as a JSON object, for example {"site":"ams1","status":"active","q":"core"}. A list matches any of its items: {"role":["router","switch"]}. NetBox silently ignores filter names it does not know, so when the filters match every object of the type the result carries a warning.

Full NetBox objects are large. Use fields (for example id,name,status) or brief to keep results small. Results are pruned: url and display_url, empty values, nulls and the nested counters are left out, except for nulls in fields you asked for. raw returns the objects untouched. Results are paged with limit (default 25, maximum 1000) and offset, next_offset is null on the last page.

Writing

create_objects takes a JSON object, or a JSON array of up to 500 objects that NetBox creates in one transaction. Related objects are referenced by ID or by a unique field, for example {"site":{"slug":"home"},"role":2}, so create sites, roles and types before the objects that use them. It returns the ID and name of every new object.

update_object sends only the fields you give (PATCH) and answers with what changed, verbose returns the whole object. update_objects takes an array of objects that each carry an id. delete_object and delete_objects (a JSON array or comma separated list of IDs) cannot be undone and NetBox may delete dependent objects too.

Write requests are never retried, a repeated request could be applied twice. Every change shows up in get_changelog.

Build

go build -o mcp-netbox .

Usage

Add to your MCP client config:

{
  "mcpServers": {
    "mcp-netbox": {
      "command": "/path/to/mcp-netbox",
      "env": {
        "NETBOX_URL": "https://netbox.simoncor.net",
        "NETBOX_TOKEN": "your-token-here"
      }
    }
  }
}

The server communicates over stdio using the MCP protocol. With -http :8080 it serves streamable HTTP instead.