Skip to content
Back to search

netbox-mcp

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
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/zariel--netbox-mcp/badge.svg)](/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
  1. # netbox-mcp
  2. An [MCP](https://modelcontextprotocol.io) server that lets agents read and
  3. manage [NetBox](https://netboxlabs.com/docs/netbox/). It serves streamable HTTP
  4. at `/mcp` and is built on the official
  5. [MCP Go SDK](https://github.com/modelcontextprotocol/go-sdk).
  6. The tools are generic over NetBox object types, named `app_label.model` (for
  7. example `ipam.prefix` or `dcim.interface`). The server resolves each type to its
  8. REST endpoint through `/api/core/object-types/`, so plugin models work without
  9. configuration. The type list is cached and reloaded when an unknown type is
  10. requested.
  11. There is no dry-run or confirmation step. Write tools carry MCP annotations
  12. (`destructiveHint` on update and delete), and human approval belongs to the MCP
  13. client. NetBox validation errors are returned verbatim as tool errors so the
  14. model can correct its request.
  15. ## Configuration
  16. | Variable | Required | Meaning |
  17. | --- | --- | --- |
  18. | `NETBOX_URL` | yes | NetBox base URL, e.g. `http://netbox.default.svc.cluster.local`. A path prefix is preserved. |
  19. | `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. |
  20. | `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`. |
  21. | `MCP_AUTH_TOKEN` | yes | Bearer token every MCP request must present. Requests without it receive `401`. |
  22. | `LISTEN_ADDR` | no | Listen address, default `:8000`. |
  23. The server exits at startup if a required variable is missing or invalid. Logs
  24. are JSON on stderr and contain request metadata only, never headers or bodies.
  25. ## Tools
  26. | Tool | Kind | Arguments |
  27. | --- | --- | --- |
  28. | `list_object_types` | read | none |
  29. | `get_objects` | read | `object_type`, `filters`, `fields`, `brief`, `limit`, `offset`, `ordering` |
  30. | `get_object` | read | `object_type`, `id`, `fields`, `brief` |
  31. | `search_objects` | read | `query`, `object_types`, `fields`, `brief`, `limit` (per type, default 5) |
  32. | `get_changelogs` | read | `filters`, `fields`, `brief`, `limit`, `offset`, `ordering` |
  33. | `list_available` | read | `kind` (`prefixes`, `ips`, `vlans`), `parent_type`, `parent_id`, `limit` |
  34. | `create_objects` | write | `object_type`, `objects` |
  35. | `update_objects` | write, destructive | `object_type`, `objects` (each with `id`) |
  36. | `delete_objects` | write, destructive | `object_type`, `ids` |
  37. | `allocate_available` | write | `kind`, `parent_type`, `parent_id`, `objects` |
  38. `filters` takes NetBox filter parameters. An array value sends the parameter
  39. once per element, which NetBox treats as OR, and `null` matches an unset
  40. relation. List results are returned as `{count, results}`; use `fields` or
  41. `brief` to keep responses small.
  42. NetBox's REST API has no global search, so `search_objects` queries each type's
  43. `q` filter concurrently. It returns brief matches unless `fields` is given,
  44. omits types without matches, and reports per-type failures, such as a missing
  45. view permission, under `errors`.
  46. The write tools take a list of objects. A single object is sent as one object
  47. and NetBox returns one object; several are sent as one bulk request, which
  48. NetBox applies atomically and answers with a list. Updates use `PATCH`, so each
  49. object needs only `id` and the fields to change.
  50. Available resources exist under these parents:
  51. | `kind` | `parent_type` |
  52. | --- | --- |
  53. | `prefixes` | `ipam.prefix` |
  54. | `ips` | `ipam.prefix`, `ipam.iprange` |
  55. | `vlans` | `ipam.vlangroup` |
  56. Allocating a prefix requires `prefix_length`; IPs accept `{}`; VLANs require
  57. `name`.
  58. ## NetBox permissions
  59. Use a dedicated non-superuser NetBox user for the server's token, so that NetBox
  60. remains the authority for what agents may change. Grant it an ObjectPermission
  61. with the view, add, change and delete actions on every object type except
  62. `users.*`, which keeps agents from managing accounts, tokens and permissions.
  63. That grant covers `core.objecttype` and `core.objectchange`, which type
  64. resolution and changelogs read. Narrow the actions or add constraints
  65. to restrict what agents can modify.
  66. ## Deployment
  67. The container image is `ghcr.io/zariel/netbox-mcp`. It runs as UID 65532 from a
  68. distroless static base and listens on port 8000. Name the container port `http`;
  69. TCP probes are sufficient.
  70. Sessions are stateless and responses are plain JSON, so restarts do not break
  71. connected clients and no session affinity is needed. `GET` and `DELETE` on
  72. `/mcp` return `405`, as the streamable HTTP transport allows for stateless
  73. servers.
  74. The server expects a gateway in front of it to authenticate users and to
  75. replace the caller's `Authorization` header with `Bearer <MCP_AUTH_TOKEN>`.
  76. Requests that bypass the gateway are rejected because they lack that token.
  77. ## Development
  78. ```sh
  79. gofmt -l .
  80. go vet ./...
  81. go test -race ./...
  82. docker build -t netbox-mcp .
  83. ```
  84. The tests run each tool through the SDK's in-memory MCP transport against a fake
  85. NetBox and assert the method, path, query, authorization header and body that
  86. NetBox receives.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.