netbox-mcp-server
A Model Context Protocol server that lets an AI assistant read — and, if its token allows, write — your NetBox instance: DCIM, IPAM, circuits, virtualization, tenancy, power, and whatever plugins that instance has installed.
Written in TypeScript on the official @modelcontextprotocol/sdk. Runs locally over
stdio as a subprocess of an MCP-aware client (Claude Desktop, Claude Code, Cursor,
Codex).
Five tools, not several hundred. The object types, fields, filters and enum values
are not hard-coded — they are derived at runtime from the connected instance's own
/api/schema/ document, so the surface describes your NetBox, including its plugins
and custom fields. A tools/list response is about 12,000 characters of descriptions and
schemas, roughly 3,000 tokens.
Installing this? Paste this into Claude, ChatGPT, or any assistant that can browse and run commands:
Read https://raw.githubusercontent.com/zenixsolutions/netbox-mcp-server/main/AGENTS.md and follow it to install the NetBox MCP server on my Mac.
AGENTS.mdis a step-by-step runbook written for an AI assistant to execute without guessing. Humans can use the Quick start below instead.
Quick start
There is nothing to clone or build. Your MCP client launches the server with npx, which
fetches the published package on first use.
You need:
- Node.js >= 20.11 (
node --version). Node 18 is end-of-life and unsupported. - A NetBox API token — see Creating the token below.
Claude Desktop
Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or
%APPDATA%\Claude\claude_desktop_config.json (Windows). Add the netbox entry to the
mcpServers object you already have; do not replace the file.
{
"mcpServers": {
"netbox": {
"command": "/opt/homebrew/bin/npx",
"args": ["-y", "@zenixsolutions/netbox-mcp"],
"env": {
"NETBOX_URL": "https://netbox.yourcompany.com",
"NETBOX_TOKEN": "your-api-token"
}
}
}
}
Use the absolute path from command -v npx as command. Claude Desktop is launched
from Finder and never sources your shell profile, so a bare "npx" — like a bare
"node" — often fails with spawn npx ENOENT. Fully quit Claude Desktop (Cmd-Q) and
reopen it after editing the config.
Claude Code
read -rs NETBOX_TOKEN # paste the token; nothing is echoed
claude mcp add netbox \
--env NETBOX_URL="https://netbox.yourcompany.com" \
--env NETBOX_TOKEN="$NETBOX_TOKEN" \
-- "$(command -v npx)" -y @zenixsolutions/netbox-mcp
unset NETBOX_TOKEN
Do not put the token in ~/.zshrc or any other shell profile. It belongs in the client
config and nowhere else.
Pin the version — "@zenixsolutions/[email protected]" — if you do not want the tool
surface to change between restarts. This project is below 1.0.0, and the
CHANGELOG is where surface changes are recorded. Other clients:
AGENTS.md.
Then ask your assistant: "Using the netbox tools, list the first 5 sites."
Creating the token
NetBox → your user menu → API Tokens → Add a token.
- Leave Write enabled unchecked unless the assistant is meant to change infrastructure records. This is the only write control there is (see Write access).
- Set an expiry date.
- Constrain the token's object permissions to what the assistant actually needs.
Installing the skill as well
The quick start above installs the tools. The netbox-modeling skill installs the
judgement that drives them — build order, required fields, deprecated models, and a
plan you confirm before anything is written.
docs/installing-the-skill.md is the per-surface page, with exact paths and config blocks for all three places this server runs:
- Claude (Desktop, Code, Cowork) — one step for both halves:
/plugin marketplace add ZenixSolutions/netbox-mcp-serverthen/plugin install netbox-mcp@zenix-solutions. The plugin carries the server config and the skill, and prompts for the URL and token. - ChatGPT desktop (a Codex host) — TOML at
~/.codex/config.toml, skill in~/.agents/skills/. - Grok Build (xAI's local agent) — TOML at
~/.grok/config.toml, skill in~/.grok/skills/; it also reads the Claude plugin above with no configuration.
That page also covers what updates itself and what does not — briefly: Claude plugins do, at session start; nothing else does.
The five tools
The intended path for a change is netbox_discover → netbox_describe → netbox_write.
netbox_global_search is the shortcut past that: looking one named object up costs a
single call rather than three. A read where you already know the type — dcim.device,
ipam.prefix — is one call to netbox_read.
Object type keys are <app>.<model>, singular. Plugin models are
plugins.<plugin>.<model> and are not guessable, which is what netbox_discover is for.
A few behaviours worth knowing:
- A wrong object type or filter name is refused locally, with near-misses or the
valid filter names listed. NetBox itself answers
200and the entire unfiltered collection for a query parameter it does not recognise, so the server rejects unknown filters rather than passing them through. netbox_writevalidatesdataagainst the instance's schema before sending anything. A rejection returns the same descriptionnetbox_describewould have.updateis a partial write. Only the fields present indatachange.deleterequiresconfirmto equal the object's currentdisplayvalue. Read the object first, copydisplay, pass it back. NetBox cascades deletes — removing a site can remove its racks, devices and prefixes — and it cannot be undone.netbox_readandnetbox_global_searchreturn Markdown by default or JSON on request. Lists page at 50 by default (max 1000) and reporttotal,has_moreandnext_offset; any response over 25,000 characters is truncated with the offset to resume from.
Layering costs round-trips. A trivial read that one netbox_read call answers has
been observed taking four calls, and a name lookup ten. That is measured, not estimated,
and rewording the tool descriptions did not fix it — see
docs/reference/eval-model-in-loop.md and
docs/reference/eval-results.md. What it buys is a
tools/list that fits in a context window.
The design rationale is RFC-003.
Configuration
Three environment variables. There are no others.
The instance's OpenAPI document is fetched once and cached on disk under
$XDG_CACHE_HOME/netbox-mcp (or ~/.cache/netbox-mcp), keyed by the NetBox version and
installed plugin set from /api/status/. Upgrading NetBox or adding a plugin invalidates
it; a cache that cannot be read or written is never fatal.
Write access
Write access is controlled by the NetBox token, not by this server. There is no
server-side read-only switch, and that is deliberate: an environment variable that hides
the write tool is a suggestion, whereas a token with write_enabled unchecked and scoped
object permissions is enforced by NetBox, where no tool argument can reach it.
Issue a read-only token for anyone who does not need to change records. If a write is
refused, NetBox answers 403 and the server's error text names the likely cause —
including the token's write_enabled flag.
More on operating this safely, including prompt-injection risk with a write-enabled token: SECURITY.md.
Command-line surface
The binary is normally launched by a client, but it has four verbs for verifying an
install. Substitute node dist/index.js for netbox-mcp if you built from a clone.
--check is the verb for diagnosing a configuration problem. --help returns before any
configuration is read, so it prints the same output whether your credentials are correct,
wrong, or absent — it can never surface a config error.
# Is the configuration usable? Names the offending variable and exits 78 if not.
NETBOX_URL=https://netbox.corp.com NETBOX_TOKEN="$NETBOX_TOKEN" netbox-mcp --check
# -> ok: netbox-mcp-server v0.2.0 configured for https://netbox.corp.com
# Does the binary work at all? Needs no credentials and makes no network calls.
netbox-mcp --list-tools
# -> netbox_global_search / netbox_discover / netbox_describe / netbox_read / netbox_write
# 5 tools registered. (on stderr)
# Do the credentials work against NetBox itself?
curl -sS -H "Authorization: Token $NETBOX_TOKEN" \
"$NETBOX_URL/api/dcim/sites/?limit=1" | head -c 200
Keep the token in a shell variable rather than typing it into a command: command lines
land in shell history and are visible in ps to every process on the machine.
Compatibility and limitations
The honest source is docs/compatibility.md. In short:
- Contract-tested against NetBox 4.6.0 with
netbox_inventory2.6.0 — 435 checks, 0 defects. That is one instance, which is evidence, not a supported range. Response shapes differ across NetBox versions; please include yours in any bug report. The compatibility doc explains how to run the suite against your own instance with a read-only token, and what to send back. - stdio only. There is no remote HTTP transport, so clients that only speak HTTP (ChatGPT connectors, Grok connectors) cannot use this.
- One plugin has been verified. Others have never been tried.
- Known limitations — round-trip cost, the
device_idargument name, no file uploads, no GraphQL — are listed there rather than duplicated here.
Building from a clone
For contributors, and for machines that cannot reach the npm registry:
git clone https://github.com/zenixsolutions/netbox-mcp-server.git
cd netbox-mcp-server
npm ci
npm run build
node dist/index.js --check # exits 0 when NETBOX_URL and NETBOX_TOKEN are usable
Run npm ci in a shell with no NETBOX_TOKEN exported: it executes the install
scripts of every package in the dependency tree, and each one inherits your environment.
Then use the same client config as above, with command set to the absolute path from
command -v node and args set to the absolute path of dist/index.js:
"netbox": {
"command": "/opt/homebrew/bin/node",
"args": ["/Users/YOU/netbox-mcp-server/dist/index.js"],
"env": { "NETBOX_URL": "...", "NETBOX_TOKEN": "..." }
}
Tildes (~) are not expanded by MCP clients — both paths must be absolute.
Troubleshooting
The most common failure by far: spawn npx ENOENT / spawn node ENOENT in a GUI
client. Claude Desktop is launched from Finder and never sources your ~/.zshrc, so an
npx or node installed by nvm/fnm/asdf/Volta/Homebrew is invisible to it. Put the
absolute path from command -v npx (or command -v node) in the config, not the bare
string "npx".
Second most common: Missing required environment variable .... Run --check with
the same variables the config sets — it names the variable and exits 78.
Claude Desktop logs each server separately:
tail -f ~/Library/Logs/Claude/mcp-server-netbox.log
Full table of symptoms and fixes: AGENTS.md.
Development
npm run dev # tsx watch src/index.ts
npm run build # tsc -> dist/
npm run typecheck # tsc --noEmit, sources + tests
npm run lint # eslint
npm run format:check # prettier --check
npm test # vitest run
npm run test:contract # opt-in, against a live instance with a read-only token
npm run eval # opt-in, evals/
src/
index.ts entry point; argv parsing (--help/--version/--check/--list-tools)
server.ts server construction and introspection
config.ts env parsing / validation
constants.ts character limits, page sizes, env var names
client.ts axios-based NetBox client
errors.ts NetBox API error formatting
formatting.ts markdown rendering + pagination payload
schema/ fetch, cache and interpret the instance's /api/schema/
schemas/common.ts shared Zod schemas
tools/layered/ the five tools: search, discover, describe, read, write
skills/
netbox-modeling/ agent skill, versioned with the tool contract it names
scripts/
check-changelog.mjs release guard: CHANGELOG has a section for the current version
Each tool's description text lives beside its implementation in
src/tools/layered/*.ts — that text is the interface most models actually see, and it is
reviewed as such.
Contributing
Issues and pull requests welcome — see CONTRIBUTING.md.
Security vulnerabilities should be reported privately, not as public issues. See SECURITY.md.
Disclaimer
This is an independent, community-maintained project. It is not affiliated with, endorsed by, or supported by NetBox Labs or the NetBox open-source project. "NetBox" is a trademark of its respective owner.
Provided as-is under the MIT license. You are responsible for what an AI assistant does with the credentials you give it — read SECURITY.md before issuing a write-enabled token for a production NetBox instance.
License
MIT — see LICENSE.
