S2 Netbox MCP

s2-netbox-mcp

A local MCP server that exposes LenelS2 S2 NetBox NBAPI operations — persons/credentials, access levels, portals/readers/outputs, time specs, holidays, portal/reader groups, threat levels, events/activity, and partitions/UDF lists — as MCP tools usable from any MCP-compatible client (Claude, Gemini/Antigravity, etc.).

Not the open-source netboxlabs.com "NetBox" DCIM/IPAM tool. This targets

LenelS2's S2 NetBox physical access-control appliance and its NBAPI

(Web-Based API for S2 NetBox and S2 Global, LenelS2 doc #API-UG-14).

Newer NBAPI v1 (doc #API-UG-22, April 2024) and v2 (doc #API2-UG-8,

April 2025) guides also exist — see docs/reference/

for reference copies. Both have now been diffed against this server's tool

surface command by command and parameter by parameter:

docs/reference/nbapi-command-diff.md

records the result, including which documented commands are deliberately

not implemented and why.

[!WARNING]

This connects to a real physical security system. With the wrong

configuration, an AI agent using this server could unlock doors or modify

access-control data on a live building. It is read-only by default —

writes and destructive operations (lock/unlock, add/modify/delete) each

require their own explicit opt-in environment variable (see **Write

access** below) — but you are responsible for what you enable and which

MCP client/model you point at it. See SECURITY.md before deploying

anything beyond read-only against a production controller.

Install

Three steps, plus an optional fourth: check the requirements, install the server, register it with your MCP client, and optionally add the workflow skill. Before the first real call, also check the controller prerequisites.

Requirements

• Node.js >= 18.17 (tested on Node 24), which includes npm. If Node.js isn't installed, on Windows you can install it with winget, then open a new terminal so node/npm are on your PATH:

  winget install OpenJS.NodeJS.LTS

• An S2 NetBox controller reachable from wherever this server runs, with the NBAPI enabled and configured for session-login authentication (not MAC authentication — see the spec for why that's out of scope for v1)
• A NetBox operator account with API access and read permission on the resources you want to query

Install the MCP server

Two ways to get the server:

Option A — npm (no clone needed):

npm install -g s2-netbox-mcp

This installs the s2-netbox-mcp binary; point your MCP client's command at s2-netbox-mcp directly (no node dist/index.js needed).

Option B — clone and build:

npm install

npm run build

Either way, copy .env.example to .env and fill in real values (or provide the same variables directly in your shell / in the Claude Code MCP server config's env block — see below). Never commit `.env` — it's already gitignored.

cp .env.example .env

edit .env

Keeping the password out of plaintext (1Password). NETBOX_PASSWORD may be a 1Password secret reference such as op:// / /password, both in .env and in an MCP client's env block. Launch the server (or any script that talks to the controller) under op run, which resolves the reference into a real environment variable before node starts. For an MCP client, make op run the command and the node invocation its arguments:

op run --account <account> --no-masking -- node /path/to/s2-netbox-mcp/dist/index.js

dotenv never overrides a variable that is already set, so the resolved value wins over the literal op://… text in .env. Without op run, that literal text is sent as the password and login fails with NBAPI error 5 (authentication failure).

Start the server directly to sanity-check it boots (it just waits on stdio for an MCP client — Ctrl+C to stop; this also sends Logout if a session was opened):

npm start

Registering with an MCP client

This server works with any MCP client that speaks the standard mcpServers stdio config shape — Claude Code, Antigravity, and Gemini CLI have all been verified against it directly. Which JSON to use depends on which install option you picked above:

If you installed via npm (Option A above):

{

"mcpServers": { "s2-netbox-mcp": { "command": "s2-netbox-mcp", "env": { "NETBOX_BASE_URL": "https://netbox.example.internal", "NETBOX_USERNAME": "svc-account", "NETBOX_PASSWORD": "REPLACE_ME", "NETBOX_ALLOW_INSECURE_TLS": "false" } } } }

If you cloned and built locally (Option B above):

{

"mcpServers": { "s2-netbox-mcp": { "command": "node", "args": ["/absolute/path/to/s2-netbox-mcp/dist/index.js"], "env": { "NETBOX_BASE_URL": "https://netbox.example.internal", "NETBOX_USERNAME": "svc-account", "NETBOX_PASSWORD": "REPLACE_ME", "NETBOX_ALLOW_INSECURE_TLS": "false" } } } }

Replace the args path with the actual absolute path to dist/index.js on your machine, and replace the env values with your real controller details (or omit env entirely and rely on a .env file next to the project if you prefer — either works, since src/index.ts loads .env via dotenv before reading process.env). Run npm run build first so dist/index.js exists.

Where to put that JSON depends on the client:

All three use the identical mcpServers object shape shown above — only the surrounding file and location differ.

Install the workflow skill (optional)

The s2-netbox-workflows Agent Skill adds step-by-step onboard, offboard, event-unlock, and badge-denied workflows on top of this server's tools. It needs the server registered above.

Install in Claude Code (plugin):

/plugin marketplace add J-MaFf/s2-netbox-mcp

/plugin install s2-netbox-workflows@s2-netbox-mcp

The plugin, in plugins/s2-netbox-workflows/, ships only the skill. It doesn't bundle or launch the MCP server, so it won't start a second server next to the one you already registered. To pick up a newer version, run claude plugin marketplace update s2-netbox-mcp, then claude plugin update s2-netbox-workflows@s2-netbox-mcp, then restart Claude Code.

Install manually (Claude Code or any agent that reads Agent Skills): copy or symlink plugins/s2-netbox-workflows/skills/s2-netbox-workflows/ into your agent's skills directory. For Claude Code that's ~/.claude/skills/ for every project, or .claude/skills/ in a single project. The skill loads on its own when a request matches it, for example "onboard Jane Doe with card 12345", "unlock the lobby Friday 8 to 5", or "why was badge 4471 denied at the dock door?".

Controller prerequisites

Before this server can talk to your controller, on the NetBox web UI go to Configuration → Site Settings → Network Controller → Data Integration and confirm all three of these are checked:

• Enable V2
• Use Authentication
• Use login username/password for authentication (requires setup privilege)

The NBAPI user account also needs a role with NBAPI read access (see the NBAPI doc's "Setting Up User Roles for the API" section) — a login that succeeds but can't read the resources this server queries will surface as FAIL or APIERROR responses per tool call. If you set NETBOX_ENABLE_WRITES, that role needs Read-Write API privilege instead (Configuration → Site Settings → User Roles → API Privilege) — Read-Only suffices only for the read tools.

Troubleshooting

• "Login succeeds but every other command returns `APIERROR 5`." This is the live-observed symptom of the *Use login username/password for authentication (requires setup privilege)* checkbox being unticked, which puts the controller in MAC-authentication mode instead of session-login mode (MAC auth is out of scope for this server — see the spec). Login still returns SUCCESS with a session ID, but every subsequent command — including Logout — fails with APIERROR 5. Fix: tick that checkbox on the *Data Integration* tab. This server's client detects this exact pattern (a successful re-login followed by another APIERROR 5) and surfaces a tool error naming the checkbox directly.
• "HTTP 410 Gone." The configured NETBOX_API_PATH is not served by this controller. NetBox 6.x serves the NBAPI at /nbws/goforms/nbapi (the default this server uses); the 2020 doc's /goforms/nbapi path is deregistered on 6.x and returns 410 for every request. If you're on a pre-6.x controller, set NETBOX_API_PATH=/goforms/nbapi explicitly; if you're on 6.x and still see this, double-check NETBOX_API_PATH isn't set to something else by mistake.

Environment variables

| NETBOX_UNLOCK_HOLIDAY_GROUPS | No | 8,7,6 | The holiday groups reserved for the m