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://<vault>/<item>/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).

Star

... View full README on GitHub