Skip to content

NetBox Agent MCP

A read-only Model Context Protocol server for NetBox, designed for agentic LLM workflows.

PyPI CI Python License: MIT

Why this exists

The server is built around four patterns agents need most:

  • Deep relational queries via dotted selection paths (site.region.name).
  • Pre-computed follow-up filters in search and list responses — no hand-parsing IDs.
  • Live schema introspection so agents don't guess at field names.
  • Hard-capped auto-pagination — no "partial-result hallucinations."

Quick start

# Zero install (always latest)
uvx netbox-agent-mcp

# Persistent install
uv tool install netbox-agent-mcp

Register with your MCP client (Claude Code example):

claude mcp add --transport stdio netbox \
  --env NETBOX_URL=https://netbox.example.com/ \
  --env NETBOX_TOKEN=<your-token> \
  -- uvx netbox-agent-mcp

Full install + client-configuration instructions are in the README.

Where to go next

  • :material-book-open-variant: Developer guide

    Design rationale, layer responsibilities, add-a-type / add-a-tool checklists, testing strategy, and extension procedures.

  • :material-robot-outline: Agent system prompt

    Recommended system prompt for agents using this server — encodes the response-shape contract and intent routing.

  • :material-history: Changelog

    Release notes and version history.

  • :material-shield-check: Security

    How to report vulnerabilities privately, and what's in scope.

  • :material-handshake: Contributing

    Prerequisites, setup, workflow, and conventions for contributors.

  • :material-package-variant: PyPI

    All published versions, direct downloads, and release metadata.

Ten read-only tools

Intent Tool
Free-text search across NetBox netbox_search
Filtered list (bounded / exhaustive) netbox_get / netbox_get_all
"Top N devices by X" structural aggregation netbox_aggregate_by_device
Composite device view netbox_device_profile
Cross-table IP fan-out (incl. free-text descriptions) netbox_find_ip_references
Cable path tracing netbox_trace_path
Free-capacity queries (IPs, prefixes, VLANs, ASNs) netbox_get_available
Live schema introspection netbox_inspect_type
Raw GraphQL escape hatch netbox_query

See the README tool reference for full argument shapes and worked examples. Tool docstrings are also visible to agents at runtime via MCP.

Read-only by design

No create/update/delete tools. Writes are deliberately excluded to keep the attack surface minimal. Users who need writes call NetBox's REST or web UI directly.