Back to search
netbox-mcp
MCP serverGitHub
Read-write NetBox MCP server
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/zariel--netbox-mcp)HTML
<a href="/listings/zariel--netbox-mcp"><img src="/api/listings/zariel--netbox-mcp/badge.svg" alt="findsafeskills safety rating" /></a>Install
i
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 109 lines
- # netbox-mcp
- An [MCP](https://modelcontextprotocol.io) server that lets agents read and
- manage [NetBox](https://netboxlabs.com/docs/netbox/). It serves streamable HTTP
- at `/mcp` and is built on the official
- [MCP Go SDK](https://github.com/modelcontextprotocol/go-sdk).
- The tools are generic over NetBox object types, named `app_label.model` (for
- example `ipam.prefix` or `dcim.interface`). The server resolves each type to its
- REST endpoint through `/api/core/object-types/`, so plugin models work without
- configuration. The type list is cached and reloaded when an unknown type is
- requested.
- There is no dry-run or confirmation step. Write tools carry MCP annotations
- (`destructiveHint` on update and delete), and human approval belongs to the MCP
- client. NetBox validation errors are returned verbatim as tool errors so the
- model can correct its request.
- ## Configuration
- | Variable | Required | Meaning |
- | --- | --- | --- |
- | `NETBOX_URL` | yes | NetBox base URL, e.g. `http://netbox.default.svc.cluster.local`. A path prefix is preserved. |
- | `NETBOX_PUBLIC_URL` | no | URL users reach NetBox at, e.g. `https://netbox.example.com`. NetBox builds the `url` and `display_url` links in its responses from the request, so without this they name `NETBOX_URL`. The server sends this URL's host and scheme as `X-Forwarded-Host` and `X-Forwarded-Proto`, which NetBox trusts by default; its path is ignored, because NetBox's `BASE_PATH` applies to both URLs. |
- | `NETBOX_TOKEN` | yes | NetBox API token. Tokens starting with `nbt_` are v2 tokens and are sent as `Authorization: Bearer`; others are legacy v1 tokens sent as `Authorization: Token`. |
- | `MCP_AUTH_TOKEN` | yes | Bearer token every MCP request must present. Requests without it receive `401`. |
- | `LISTEN_ADDR` | no | Listen address, default `:8000`. |
- The server exits at startup if a required variable is missing or invalid. Logs
- are JSON on stderr and contain request metadata only, never headers or bodies.
- ## Tools
- | Tool | Kind | Arguments |
- | --- | --- | --- |
- | `list_object_types` | read | none |
- | `get_objects` | read | `object_type`, `filters`, `fields`, `brief`, `limit`, `offset`, `ordering` |
- | `get_object` | read | `object_type`, `id`, `fields`, `brief` |
- | `search_objects` | read | `query`, `object_types`, `fields`, `brief`, `limit` (per type, default 5) |
- | `get_changelogs` | read | `filters`, `fields`, `brief`, `limit`, `offset`, `ordering` |
- | `list_available` | read | `kind` (`prefixes`, `ips`, `vlans`), `parent_type`, `parent_id`, `limit` |
- | `create_objects` | write | `object_type`, `objects` |
- | `update_objects` | write, destructive | `object_type`, `objects` (each with `id`) |
- | `delete_objects` | write, destructive | `object_type`, `ids` |
- | `allocate_available` | write | `kind`, `parent_type`, `parent_id`, `objects` |
- `filters` takes NetBox filter parameters. An array value sends the parameter
- once per element, which NetBox treats as OR, and `null` matches an unset
- relation. List results are returned as `{count, results}`; use `fields` or
- `brief` to keep responses small.
- NetBox's REST API has no global search, so `search_objects` queries each type's
- `q` filter concurrently. It returns brief matches unless `fields` is given,
- omits types without matches, and reports per-type failures, such as a missing
- view permission, under `errors`.
- The write tools take a list of objects. A single object is sent as one object
- and NetBox returns one object; several are sent as one bulk request, which
- NetBox applies atomically and answers with a list. Updates use `PATCH`, so each
- object needs only `id` and the fields to change.
- Available resources exist under these parents:
- | `kind` | `parent_type` |
- | --- | --- |
- | `prefixes` | `ipam.prefix` |
- | `ips` | `ipam.prefix`, `ipam.iprange` |
- | `vlans` | `ipam.vlangroup` |
- Allocating a prefix requires `prefix_length`; IPs accept `{}`; VLANs require
- `name`.
- ## NetBox permissions
- Use a dedicated non-superuser NetBox user for the server's token, so that NetBox
- remains the authority for what agents may change. Grant it an ObjectPermission
- with the view, add, change and delete actions on every object type except
- `users.*`, which keeps agents from managing accounts, tokens and permissions.
- That grant covers `core.objecttype` and `core.objectchange`, which type
- resolution and changelogs read. Narrow the actions or add constraints
- to restrict what agents can modify.
- ## Deployment
- The container image is `ghcr.io/zariel/netbox-mcp`. It runs as UID 65532 from a
- distroless static base and listens on port 8000. Name the container port `http`;
- TCP probes are sufficient.
- Sessions are stateless and responses are plain JSON, so restarts do not break
- connected clients and no session affinity is needed. `GET` and `DELETE` on
- `/mcp` return `405`, as the streamable HTTP transport allows for stateless
- servers.
- The server expects a gateway in front of it to authenticate users and to
- replace the caller's `Authorization` header with `Bearer <MCP_AUTH_TOKEN>`.
- Requests that bypass the gateway are rejected because they lack that token.
- ## Development
- ```sh
- gofmt -l .
- go vet ./...
- go test -race ./...
- docker build -t netbox-mcp .
- ```
- The tests run each tool through the SDK's in-memory MCP transport against a fake
- NetBox and assert the method, path, query, authorization header and body that
- NetBox receives.
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.