S2 Netbox MCP server

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.

Read-only by default. With no write-related environment variables set, this server registers only query/read NBAPI commands:

• Login
• Logout
• GetAPIVersion
• GetPerson
• SearchPersonData
• GetCardAccessDetails
• GetCardFormats
• GetAccessLevel(s)
• GetAccessLevelGroup(s)
• GetPortals
• GetReader(s)
• GetOutputs

By default, this server registers only the query/read commands listed above. It does not register any write, delete, or control operations against the controller until you explicitly opt in via the environment variables in Write access below. Among the read-only tools, four are composites, findportals, getunlockwindow, getdailyunlockwindow, and getreaderaccess_history, which issue only read commands. Note there is no GetPortal (singular) command; only GetPortals (plural, paginated, no single-portal filter) exists on the real NBAPI.

Requirements

NBAPI enabled and configured for session-login authentication (not MAC authentication — see the spec for why that's out of scope for v1)

• Node.js >= 18.17 (tested on Node 24)
• An S2 NetBox controller reachable from wherever this server runs, with the

resources you want to query

• A NetBox operator account with API access and read permission on the

Setup

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

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

Shortened. The full README is on GitHub.