Skip to content
Back to search

netbox-mcp-server

Model Context Protocol (MCP) server for read-only interaction with NetBox data in LLMs

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/netboxlabs/netbox-mcp-server with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/netboxlabs/netbox-mcp-server'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/netboxlabs--netbox-mcp-server/badge.svg)](/listings/netboxlabs--netbox-mcp-server)

HTML

<a href="/listings/netboxlabs--netbox-mcp-server"><img src="/api/listings/netboxlabs--netbox-mcp-server/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 · 407 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # NetBox MCP Server
  2. > **⚠️ Breaking Change in v1.0.0**: The project structure has changed.
  3. > If upgrading from v0.1.0, update your configuration:
  4. > - Change `uv run server.py` to `uv run netbox-mcp-server`
  5. > - Update Claude Desktop/Code configs to use `netbox-mcp-server` instead of `server.py`
  6. > - Docker users: rebuild images with updated CMD
  7. > - See [CHANGELOG.md](CHANGELOG.md) for full details
  8. This is a simple read-only [Model Context Protocol](https://modelcontextprotocol.io/) server for NetBox. It enables you to interact with your data in NetBox directly via LLMs that support MCP.
  9. 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.
  10. ## Community
  11. For chat, use cases, and general MCP discussion, join the NetBox community at [netdev.chat](https://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](https://github.com/netboxlabs/netbox-mcp-server/issues).
  12. ## Tools
  13. | Tool | Description |
  14. |------|-------------|
  15. | get_objects | Retrieves NetBox core objects based on their type and filters |
  16. | get_object_by_id | Gets detailed information about a specific NetBox object by its ID |
  17. | get_changelogs | Retrieves change history records (audit trail) based on filters |
  18. > Note: Core NetBox object types are always available. Plugin object types can be auto-discovered. See [Plugin Object Type Discovery](#plugin-object-type-discovery). Advanced features (GraphQL, dynamic model discovery, etc.) are deliberately out of scope. See [CONTRIBUTING.md](CONTRIBUTING.md) for the full scope statement and rationale.
  19. ## Usage
  20. 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.
  21. 2. Install dependencies:
  22. ```bash
  23. # Using UV (recommended)
  24. uv sync
  25. # Or using pip
  26. pip install -e .
  27. ```
  28. 3. Verify the server can run: `NETBOX_URL=https://netbox.example.com/ NETBOX_TOKEN=<your-api-token> uv run netbox-mcp-server`
  29. 4. Add the MCP server to your LLM client. See below for some examples with Claude.
  30. ### Claude Code
  31. #### Stdio Transport (Default)
  32. Add the server using the `claude mcp add` command:
  33. ```bash
  34. claude mcp add --transport stdio netbox \
  35. --env NETBOX_URL=https://netbox.example.com/ \
  36. --env NETBOX_TOKEN=<your-api-token> \
  37. -- uv --directory /path/to/netbox-mcp-server run netbox-mcp-server
  38. ```
  39. **Important notes:**
  40. - Replace `/path/to/netbox-mcp-server` with the absolute path to your local clone
  41. - The `--` separator distinguishes Claude Code flags from the server command
  42. - Use `--scope project` to share the configuration via `.mcp.json` in version control
  43. - Use `--scope user` to make it available across all your projects (default is `local`)
  44. After adding, verify with `/mcp` in Claude Code or `claude mcp list` in your terminal.
  45. #### HTTP Transport
  46. For HTTP transport, first start the server manually:
  47. ```bash
  48. # Start the server with HTTP transport (using .env or environment variables)
  49. NETBOX_URL=https://netbox.example.com/ \
  50. NETBOX_TOKEN=<your-api-token> \
  51. TRANSPORT=http \
  52. uv run netbox-mcp-server
  53. ```
  54. Then add the running server to Claude Code:
  55. ```bash
  56. # Add the HTTP MCP server (note: URL must include http:// or https:// prefix)
  57. claude mcp add --transport http netbox http://127.0.0.1:8000/mcp
  58. ```
  59. **Important notes:**
  60. - The URL **must** include the protocol prefix (`http://` or `https://`)
  61. - The default endpoint is `/mcp` when using HTTP transport
  62. - The server must be running before Claude Code can connect
  63. - Verify the connection with `claude mcp list` - you should see a ✓ next to the server name
  64. ### Claude Desktop
  65. Add the server configuration to your Claude Desktop config file. On Mac, edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
  66. ```json
  67. {
  68. "mcpServers": {
  69. "netbox": {
  70. "command": "uv",
  71. "args": [
  72. "--directory",
  73. "/path/to/netbox-mcp-server",
  74. "run",
  75. "netbox-mcp-server"
  76. ],
  77. "env": {
  78. "NETBOX_URL": "https://netbox.example.com/",
  79. "NETBOX_TOKEN": "<your-api-token>"
  80. }
  81. }
  82. }
  83. }
  84. ```
  85. > On Windows, use full, escaped path to your instance, such as `C:\\Users\\myuser\\.local\\bin\\uv` and `C:\\Users\\myuser\\netbox-mcp-server`.
  86. > For detailed troubleshooting, consult the [MCP quickstart](https://modelcontextprotocol.io/quickstart/user).
  87. 5. Use the tools in your LLM client. For example:
  88. ```text
  89. > Get all devices in the 'Equinix DC14' site
  90. ...
  91. > Tell me about my IPAM utilization
  92. ...
  93. > What Cisco devices are in my network?
  94. ...
  95. > Who made changes to the NYC site in the last week?
  96. ...
  97. > Show me all configuration changes to the core router in the last month
  98. ```
  99. ### Field Filtering (Token Optimization)
  100. Both `netbox_get_objects()` and `netbox_get_object_by_id()` support an optional `fields` parameter to reduce token usage:
  101. ```python
  102. # Without fields: ~5000 tokens for 50 devices
  103. devices = netbox_get_objects("devices", {"site": "datacenter-1"})
  104. # With fields: ~500 tokens (90% reduction)
  105. devices = netbox_get_objects(
  106. "devices", {"site": "datacenter-1"}, fields=["id", "name", "status", "site"]
  107. )
  108. ```
  109. **Common field patterns:**
  110. - **Devices:** `['id', 'name', 'status', 'device_type', 'site', 'primary_ip4']`
  111. - **IP Addresses:** `['id', 'address', 'status', 'dns_name', 'description']`
  112. - **Interfaces:** `['id', 'name', 'type', 'enabled', 'device']`
  113. - **Sites:** `['id', 'name', 'status', 'region', 'description']`
  114. The `fields` parameter uses NetBox's native field filtering. See the [NetBox API documentation](https://docs.netbox.dev/en/stable/integrations/rest-api/) for details.
  115. ## Configuration
  116. The server supports multiple configuration sources with the following precedence (highest to lowest):
  117. 1. **Command-line arguments** (highest priority)
  118. 2. **Environment variables**
  119. 3. **`.env` file** in the project root
  120. 4. **Default values** (lowest priority)
  121. ### Configuration Reference
  122. | Setting | Type | Default | Required | Description |
  123. |---------|------|---------|----------|-------------|
  124. | `NETBOX_URL` | URL | - | Yes | Base URL of your NetBox instance (e.g., https://netbox.example.com/) |
  125. | `NETBOX_TOKEN` | String | - | Yes | API token for authentication |
  126. | `TRANSPORT` | `stdio` \| `http` | `stdio` | No | MCP transport protocol |
  127. | `HOST` | String | `127.0.0.1` | If HTTP | Host address for HTTP server |
  128. | `PORT` | Integer | `8000` | If HTTP | Port for HTTP server |
  129. | `MCP_AUTH_TOKEN` | String | - | No | Bearer token required on the HTTP endpoint. When unset, the HTTP transport is unauthenticated. Clients send `Authorization: Bearer <token>`. |
  130. | `VERIFY_SSL` | Boolean | `true` | No | Whether to verify SSL certificates |
  131. | `ENABLE_PLUGIN_DISCOVERY` | Boolean | `false` | No | Auto-discover plugin object types at startup |
  132. | `LOG_LEVEL` | `DEBUG` \| `INFO` \| `WARNING` \| `ERROR` \| `CRITICAL` | `INFO` | No | Logging verbosity |
  133. ### Transport Examples
  134. #### Stdio Transport (Claude Desktop/Code)
  135. For local Claude Desktop or Claude Code usage with stdio transport:
  136. ```json
  137. {
  138. "mcpServers": {
  139. "netbox": {
  140. "command": "uv",
  141. "args": ["--directory", "/path/to/netbox-mcp-server", "run", "netbox-mcp-server"],
  142. "env": {
  143. "NETBOX_URL": "https://netbox.example.com/",
  144. "NETBOX_TOKEN": "<your-api-token>"
  145. }
  146. }
  147. }
  148. }
  149. ```
  150. #### HTTP Transport (Web Clients)
  151. For web-based MCP clients using HTTP/SSE transport:
  152. ```bash
  153. # Using environment variables
  154. export NETBOX_URL=https://netbox.example.com/
  155. export NETBOX_TOKEN=<your-api-token>
  156. export TRANSPORT=http
  157. export HOST=127.0.0.1
  158. export PORT=8000
  159. uv run netbox-mcp-server
  160. # Or using CLI arguments
  161. uv run netbox-mcp-server \
  162. --netbox-url https://netbox.example.com/ \
  163. --netbox-token <your-api-token> \
  164. --transport http \
  165. --host 127.0.0.1 \
  166. --port 8000
  167. ```
  168. ### Example .env File
  169. Create a `.env` file in the project root:
  170. ```env
  171. # Core NetBox Configuration
  172. NETBOX_URL=https://netbox.example.com/
  173. NETBOX_TOKEN=your_api_token_here
  174. # Transport Configuration (optional, defaults to stdio)
  175. TRANSPORT=stdio
  176. # HTTP Transport Settings (only used if TRANSPORT=http)
  177. # HOST=127.0.0.1
  178. # PORT=8000
  179. # Bearer token required on the HTTP endpoint. When unset, the endpoint is unauthenticated.
  180. # MCP_AUTH_TOKEN=a-strong-random-token
  181. # Security (optional, defaults to true)
  182. VERIFY_SSL=true
  183. # Plugin Discovery (optional, defaults to false)
  184. # ENABLE_PLUGIN_DISCOVERY=true
  185. # Logging (optional, defaults to INFO)
  186. LOG_LEVEL=INFO
  187. ```
  188. ### CLI Arguments
  189. All configuration options can be overridden via CLI arguments:
  190. ```bash
  191. uv run netbox-mcp-server --help
  192. # Common examples:
  193. uv run netbox-mcp-server --log-level DEBUG --no-verify-ssl # Development
  194. uv run netbox-mcp-server --transport http --port 9000 # Custom HTTP port
  195. ```
  196. ## Docker Usage
  197. ### Pre-built Image (Docker Hub)
  198. Pre-built multi-arch images (`linux/amd64`, `linux/arm64`) are published to Docker Hub on every tagged release:
  199. ```bash
  200. docker pull netboxlabs/netbox-mcp-server:latest
  201. ```
  202. Pin to a specific version in production. The `latest` tag tracks the most recent release and can change without notice. See the [releases page](https://github.com/netboxlabs/netbox-mcp-server/releases) for available versions:
  203. ```bash
  204. docker pull netboxlabs/netbox-mcp-server:<X.Y.Z> # exact version
  205. docker pull netboxlabs/netbox-mcp-server:<X.Y> # latest within a minor
  206. docker pull netboxlabs/netbox-mcp-server:<X> # latest within a major
  207. ```
  208. **Verify image provenance (optional but recommended).** Images are signed with [cosign](https://github.com/sigstore/cosign) (keyless, via GitHub OIDC) and ship with SLSA build provenance:
  209. ```bash
  210. cosign verify \
  211. --certificate-identity-regexp '^https://github.com/netboxlabs/netbox-mcp-server/' \
  212. --certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \
  213. netboxlabs/netbox-mcp-server:<tag>
  214. ```
  215. ### Standard Docker Image
  216. Build and run the NetBox MCP server in a container:
  217. ```bash
  218. # Build the image
  219. docker build -t netbox-mcp-server:latest .
  220. # Run with HTTP transport (required for Docker containers)
  221. docker run --rm \
  222. -e NETBOX_URL=https://netbox.example.com/ \
  223. -e NETBOX_TOKEN=<your-api-token> \
  224. -e TRANSPORT=http \
  225. -e HOST=0.0.0.0 \
  226. -e PORT=8000 \
  227. -e MCP_AUTH_TOKEN=<a-strong-random-token> \
  228. -p 8000:8000 \
  229. netbox-mcp-server:latest
  230. ```
  231. > **Note:** Docker containers require `TRANSPORT=http` since stdio transport doesn't work in containerized environments.
  232. > **⚠️ 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.
  233. **Connecting to NetBox on your host machine:**
  234. 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:
  235. ```bash
  236. # For NetBox running on host (macOS/Windows)
  237. docker run --rm \
  238. -e NETBOX_URL=http://host.docker.internal:18000/ \
  239. -e NETBOX_TOKEN=<your-api-token> \
  240. -e TRANSPORT=http \
  241. -e HOST=0.0.0.0 \
  242. -e PORT=8000 \
  243. -e MCP_AUTH_TOKEN=<a-strong-random-token> \
  244. -p 8000:8000 \
  245. netbox-mcp-server:latest
  246. ```
  247. > **Note:** On Linux, you can use `--network host` instead, or use the host's IP address directly.
  248. **With additional configuration options:**
  249. ```bash
  250. docker run --rm \
  251. -e NETBOX_URL=https://netbox.example.com/ \
  252. -e NETBOX_TOKEN=<your-api-token> \
  253. -e TRANSPORT=http \
  254. -e HOST=0.0.0.0 \
  255. -e MCP_AUTH_TOKEN=<a-strong-random-token> \
  256. -e LOG_LEVEL=DEBUG \
  257. -e VERIFY_SSL=false \
  258. -p 8000:8000 \
  259. netbox-mcp-server:latest
  260. ```
  261. The server will be accessible at `http://localhost:8000/mcp` for MCP clients. You can connect to it using your preferred method.
  262. ## Plugin Object Type Discovery
  263. 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.
  264. ### Enabling Discovery
  265. Set the `ENABLE_PLUGIN_DISCOVERY` environment variable or use the `--enable-plugin-discovery` CLI flag:
  266. ```bash
  267. # Via environment variable
  268. ENABLE_PLUGIN_DISCOVERY=true uv run netbox-mcp-server
  269. # Via CLI flag
  270. uv run netbox-mcp-server --enable-plugin-discovery
  271. # In Claude Desktop config
  272. {
  273. "mcpServers": {
  274. "netbox": {
  275. "command": "uv",
  276. "args": ["--directory", "/path/to/netbox-mcp-server", "run", "netbox-mcp-server"],
  277. "env": {
  278. "NETBOX_URL": "https://netbox.example.com/",
  279. "NETBOX_TOKEN": "<your-api-token>",
  280. "ENABLE_PLUGIN_DISCOVERY": "true"
  281. }
  282. }
  283. }
  284. }
  285. ```
  286. ### How It Works
  287. 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.
  288. 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`).
  289. ### Requirements
  290. - NetBox 4.2 or later
  291. - API token must have read access to the object-types endpoint
  292. - Plugin models must expose a REST API endpoint to be discovered
  293. ### Failure Behavior
  294. 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.
  295. ## Development
  296. Contributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) before proposing new features. We encourage filing an issue for discussion first to confirm scope fit.
  297. If your use case needs capabilities outside this project's scope, forking under Apache 2.0 is an actively supported path.
  298. ## License
  299. This project is licensed under the Apache 2.0 license. See the LICENSE file for details.

Ratings and comments

Sign in to rate this skill.

Sign in

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