Provides an optional feedback integration that uses a separate GitHub login to publish structured issues to the project repository and read maintainer replies, helping report and follow up on problems with agent operations.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@NetBox Read/Write MCP Update device 42's description to 'Core switch' and set status to active"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Built with an open-source feature focus bias.
Great for home labs or small businesses that are priced out of NetBox's official enterprise offerings. For the official managed agent integration, see the Platform MCP Server. This is an independent Reliable Collaboration Company project, not a NetBox or NetBox Labs product.
The existing read-only community MCP implementation lets agents query NetBox. This unofficial server adds writes and broader open-source Community workflows so agents can maintain existing inventory, record new assets, connect hardware and virtual resources, run jobs, and verify results. It keeps a history of agent changes and supports GitHub issue reports when something needs investigation.
Use it with your existing NetBox installation, obtained and maintained through NetBox's own repository, images or package distribution. This project distributes the MCP server and a companion plugin; it does not distribute NetBox.
Compatibility: NetBox Community 4.7.x and later. Tested on 4.7.2. Later versions are accepted but have not yet passed the recorded integration suite; changes to NetBox APIs or internals may require a compatibility update. Branching and commercial features are outside scope. Both packages are Apache-2.0 licensed.
Connect Claude Code, Codex or OpenCode to NetBox, then describe the inventory work you want done in plain language. Your agent can:
Maintain equipment records: add, update or remove sites, racks, devices, interfaces, virtual machines and other inventory, using your existing records or creating the records needed for a new installation.
Document how everything connects: record cables, trace connections, assign IP addresses and manage network prefixes and VLANs.
Handle routine administration: import or export inventory, make changes to multiple records, manage contacts and notes, and run NetBox jobs.
Check its work and explain changes: read back results and keep an operation history that helps diagnose failures or interrupted requests.
For example: “Use this equipment list to update our rack inventory, preserve existing serial numbers, and tell me which details are missing.” Or: “Find an available address in this subnet and assign it to this server's management port.”
The server supplies its own tool instructions and examples through MCP. You do not need to give the agent a separate guide. Access follows the permissions of its NetBox account. The companion plugin adds APIs for supported Community workflows that would otherwise require website forms.
See the operation map and qualification record for detailed coverage. Arbitrary third-party plugins need separate qualification.
Related MCP server: hpe-cx-mcp
Your MCP client starts the server on the agent host. The server uses a dedicated NetBox API token and stores its journal locally. NetBox permissions govern what the agent can see and change. The companion runs inside NetBox web and worker processes to fill native API gaps. The optional feedback MCP uses a separate GitHub login to publish structured issues and read maintainer replies.
Requires Python 3.11+ on POSIX and a client that can launch a local MCP process. Download the CI-built application and run its setup wizard:
curl -fL https://github.com/Reliable-Collaboration/netbox-readwrite-mcp/releases/download/v1.0.0/netbox-readwrite-mcp.pyz -o netbox-readwrite-mcp.pyz
python3 netbox-readwrite-mcp.pyz configureKeep the application at its installed path. Setup asks for the NetBox base URL,
username and API token (hidden input), creates private configuration and a stable
journal identity. It also prints a generic client configuration; use the
client-specific connection instructions below. Existing configuration and tokens
are preserved. The default directory is
~/.config/netbox-readwrite-mcp/, or under XDG_CONFIG_HOME when set.
If you already use pipx, you can install the wheel instead:
pipx install https://github.com/Reliable-Collaboration/netbox-readwrite-mcp/releases/download/v1.0.0/netbox_readwrite_mcp-1.0.0-py3-none-any.whl
netbox-readwrite-mcp configureRelease downloads include checksums, both wheels, the container plugin bundle, source distributions and the exact build revision. No checkout or local build is required.
Native REST works without the companion, with a smaller operation surface. Install the companion on both web and worker for full Community coverage. Choose the integration matching your deployment; keep your upstream NetBox image or package and existing database/configuration.
Use the Python environment that actually runs NetBox and the file that defines
its effective PLUGINS setting. These are example paths; package-managed installs
may use different locations. Run as the environment/configuration owner:
/opt/netbox/venv/bin/python -m pip install https://github.com/Reliable-Collaboration/netbox-readwrite-mcp/releases/download/v1.0.0/netbox_agent_api-1.0.0-py3-none-any.whl
/opt/netbox/venv/bin/netbox-agent-api-enable --config /opt/netbox/netbox/netbox/configuration.pyThe enable command retains existing settings/plugins, makes a private backup and
is safe to repeat. Restart NetBox web and worker with your deployment manager
(for a standard systemd installation: sudo systemctl restart netbox netbox-rq).
Separate hosts need the package installed on each. If your package manager owns
an immutable Python environment, use its supported plugin mechanism with the
same wheel; do not bypass its environment protections.
From your existing netbox-docker deployment directory:
curl -fL https://github.com/Reliable-Collaboration/netbox-readwrite-mcp/releases/download/v1.0.0/netbox-agent-api-container.tar.gz -o agent-api.tar.gz && tar -xzf agent-api.tar.gz
docker compose -f docker-compose.yml -f netbox-agent-api/compose.agent-api.yaml up -d netbox netbox-workerUse your actual base Compose filename, retaining your usual override files before our override. Podman can use its configured Compose provider. The override mounts only the prebuilt plugin, enables it on web and worker, and does not replace your NetBox image. It recreates those services while retaining the volumes and other settings in your Compose configuration. Adjust service names if they differ.
Existing plugins remain enabled. If you already set PYTHONPATH, retain its
entries alongside /opt/netbox/agent-api. If you use a custom
NETBOX_CONFIGURATION, set NETBOX_AGENT_BASE_CONFIGURATION to that original
module. See deployment details.
Use the same downloadable plugin bundle: mount its plugin directory at
/opt/netbox/agent-api in every web/worker workload, add that directory to
PYTHONPATH, and set NETBOX_CONFIGURATION=netbox_agent_api_configuration.
Retain your upstream image and set NETBOX_AGENT_BASE_CONFIGURATION if you use a
custom configuration module. Roll out the change with your normal controller.
Alternatively, use your chart's existing plugin-installation mechanism with the
released wheel. Deployment details explain the
configuration overlay and upgrades. This is a deployment recipe, not a separately
qualified Helm chart or Kubernetes operator.
Choose your client below. Run its command from the directory containing the
application you downloaded; "$PWD/netbox-readwrite-mcp.pyz" records its absolute
path so the client can start it from any project. Keep that file in place.
The NetBox token stays in the private server configuration.
claude mcp add --transport stdio --scope user netbox -- python3 "$PWD/netbox-readwrite-mcp.pyz"
claude mcp get netboxRestart Claude Code and use /mcp to check the connection. The user scope makes
it available across projects. See Claude Code's MCP documentation.
codex mcp add netbox -- python3 "$PWD/netbox-readwrite-mcp.pyz"
codex mcp get netboxStart a new Codex session and use /mcp to check the connection. For an
already-authorized unattended job, explicitly allow this server's tools for that
invocation:
codex exec -c 'mcp_servers.netbox.default_tools_approval_mode="approve"' "Your NetBox task"This leaves your saved approval settings unchanged. See Codex's MCP documentation.
For OpenCode 2:
opencode mcp add netbox --global -- python3 "$PWD/netbox-readwrite-mcp.pyz"
opencode mcp listFor OpenCode 1, including 1.18.33 used in our agent evaluation, run
python3 netbox-readwrite-mcp.pyz client-config --client opencode and merge the
printed mcp.netbox entry into your opencode.json. Then run opencode mcp list.
The released helper prints the version 1 format; version 2 uses mcp.servers
instead. See OpenCode's MCP documentation.
For a pipx installation, replace python3 "$PWD/netbox-readwrite-mcp.pyz" in the
commands above with the absolute path printed by command -v netbox-readwrite-mcp.
If you configured a custom server configuration, append --config /absolute/path/config.json
to the server command. Other MCP clients can use the generic configuration
printed by client-config.
All three clients use this unofficial read/write server's tools and built-in instructions. Local agent tests passed 24 Community workflow checks in each of OpenCode, Claude Code and Codex using GLM through LiteLLM. See the evaluation record for tested workflows, failed attempts and limits.
Provision a dedicated NetBox user with view/add/change/delete/run permissions for
the record types it will manage, plus full read access to core.view_objectchange.
Add render_config and sync when those actions are required. Use a write-enabled
API token for inventory management. Administrative operations still require
native permissions; the companion grants none. Set CHANGELOG_RETENTION = 0 and
disable independent history purge jobs so recovery has complete evidence.
python3 netbox-readwrite-mcp.pyz doctorThis checks version acceptance, companion access and history reads without
changing inventory. It reports whether the connected version is tested; it does
not prove every model-specific permission. The URL must omit /api/; HTTPS is
required except on loopback. The configured username must match the token owner.
Reconnect your MCP client and ask:
Check my NetBox connection and summarize the inventory I can access. Do not change anything.
Then give it your inventory task. For a small authorized trial:
Create a site named MCP Getting Started, slug mcp-getting-started, status active, if it does not already exist. Verify it and summarize what you changed. Repeat the check and confirm that no additional writes are needed.
The server delivers instructions at initialization and through capabilities;
get_guidance supplies detailed, version-matched examples when needed. The tool
catalog directs clients that omit initialization instructions to capabilities.
The readable guide is a documentation copy, not a setup step.
Supply observed hardware facts or an authorized discovery source for a physical
inventory; the agent cannot know which equipment you own without that input.
client-config --client opencode reprints OpenCode 1 settings without changing
identity; omit the client option for the common mcpServers format.
configure --read-only disables mutation tools. --token-file PATH supports
unattended setup without putting a token in shell arguments.
--config PATH selects a private custom config. Paths inside it are relative
to that file. Retain the instance ID and journal across restarts; consult
operations before changing database lineage.
Authenticated HTTP is available with --http 8000 --mcp-token-file PATH.
Use a separate random bearer token of at least 32 characters. It binds to
loopback /mcp; remote access requires a trusted TLS reverse proxy.
Connect the optional GitHub feedback MCP to let agents publish structured reports and read maintainer replies. NetBox and GitHub credentials are separate; no unattended response schedule is implied.
Back up the journal and NetBox database independently. Keep tokens, journals, recovery bundles and raw transcripts private. Lost responses are reconciled using original operation keys. Undo is conditional compensation: it cannot universally restore deleted graphs or reverse webhook, queue and filesystem effects. The experimental HTML adapter is unnecessary for mapped Community workflows.
Symptom | Next step |
Client cannot start the MCP | Reprint |
A manually started stdio process waits silently | Connect it through the MCP client; it is waiting for protocol input. |
Codex refuses MCP writes because approval is required | Allow the intended NetBox tools in the client's MCP approval settings. Noninteractive |
HTTP 401/403 or missing objects | Check token validity, write enablement and model/object permissions. |
Companion missing | Verify the package/mount and effective configuration on both web and worker; restart or roll out both. |
Unknown filter or stale schema | Inspect live schema and companion metadata; follow the deployment's schema-cache refresh procedure after upgrades. |
Legacy device allowlist | Explicitly migrate the restricted journal; see operations. |
Uncertain write | Preserve the original key, inspect/reconcile its receipt, and report unresolved evidence before another write. |
CI builds release assets and gates publication on the Python unit/build matrix and real NetBox 4.7.2 integration suite. The validation record and agent evaluations distinguish deterministic tests, actual GLM runs and untested combinations. Acceptance of a later NetBox version does not imply that its full workflow surface has been tested.
Contributors can clone the repository and run the disposable Podman lab described in testing. That lab is development infrastructure, not the user installation path. Small labs are the current qualification target; large-estate performance and distributed failover are outside this release.
This independent Apache-2.0 project is not endorsed by NetBox's maintainers.
This server cannot be deployed
Deterministic IT asset registry operated by AI agents over MCP. Agents propose, humans approve.
Manage ConfigDirector feature flags, remote configs, and targeting rules from AI assistants.
Give AI agents scoped, expiring API access: exact approvals, retry-safe writes, an audit log.
Zendesk configuration management for AI agents: propose, review, apply and roll back changes.
