netbox-mcp-server

Ein Model Context Protocol-Server, der einem KI-Assistenten das Lesen – und, sofern sein Token es erlaubt, das Schreiben – Ihrer NetBox-Instanz ermöglicht: DCIM, IPAM, circuits, virtualization, tenancy, power und alle Plugins, die diese Instanz installiert hat.

Geschrieben in TypeScript auf der Basis des offiziellen @modelcontextprotocol/sdk. Läuft lokal über stdio als Unterprozess eines MCP-fähigen Clients (Claude Desktop, Claude Code, Cursor, Codex).

Fünf Tools, nicht mehrere hundert. Die Objekttypen, Felder, Filter und Enum-Werte sind nicht hartkodiert – sie werden zur Laufzeit aus dem /api/schema/-Dokument der verbundenen Instanz abgeleitet, die Oberfläche beschreibt also Ihre NetBox, einschließlich ihrer Plugins und benutzerdefinierten Felder. Eine tools/list-Antwort umfasst etwa 12.000 Zeichen an Beschreibungen und Schemas, ungefähr 3.000 Tokens.

Das hier installieren? Fügen Sie das in Claude, ChatGPT oder einen Assistenten ein, der browsen und Befehle ausführen kann:

Lesen Sie https://raw.githubusercontent.com/zenixsolutions/netbox-mcp-server/main/AGENTS.md und folgen Sie dem Dokument, um den NetBox-MCP-Server auf meinem Mac zu installieren.

AGENTS.md ist eine Schritt-für-Schritt-Anleitung, die ein KI-Assistent ausführen kann, ohne raten zu müssen. Menschen können stattdessen den Schnellstart unten verwenden.

Schnellstart

Es gibt nichts zu klonen oder zu bauen. Ihr MCP-Client startet den Server mit npx, das das veröffentlichte Paket beim ersten Gebrauch abruft.

Sie benötigen:

• Node.js >= 20.11 (node --version). Node 18 ist End-of-Life und wird nicht unterstützt.

• Ein NetBox-API-Token – siehe Erstellen des Tokens unten.

Claude Desktop

Bearbeiten Sie ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) oder %APPDATA%\Claude\claude_desktop_config.json (Windows). Fügen Sie den netbox-Eintrag zu dem bereits vorhandenen mcpServers-Objekt hinzu; ersetzen Sie die Datei nicht.

{
  "mcpServers": {
    "netbox": {
      "command": "/opt/homebrew/bin/npx",
      "args": ["-y", "@zenixsolutions/netbox-mcp"],
      "env": {
        "NETBOX_URL": "https://netbox.yourcompany.com",
        "NETBOX_TOKEN": "your-api-token"
      }
    }
  }
}

Verwenden Sie den absoluten Pfad aus command -v npx als command. Claude Desktop wird aus dem Finder heraus gestartet und lädt nie Ihr Shell-Profil; daher schlägt ein nacktes "npx" – wie ein nacktes "node" – oft mit spawn npx ENOENT fehl. Beenden Sie Claude Desktop nach dem Bearbeiten der Konfiguration vollständig (Cmd-Q) und öffnen Sie es erneut.

Claude Code

read -rs NETBOX_TOKEN                       # paste the token; nothing is echoed
claude mcp add netbox \
  --env NETBOX_URL="https://netbox.yourcompany.com" \
  --env NETBOX_TOKEN="$NETBOX_TOKEN" \
  -- "$(command -v npx)" -y @zenixsolutions/netbox-mcp
unset NETBOX_TOKEN

Legen Sie das Token nicht in ~/.zshrc oder einem anderen Shell-Profil ab. Es gehört in die Client-Konfiguration und sonst nirgendwo hin.

Pinnen Sie die Version – "@zenixsolutions/netbox-mcp@0.2.0" –, wenn Sie nicht möchten, dass sich die Tool-Oberfläche zwischen Neustarts ändert. Dieses Projekt ist unter 1.0.0, und im CHANGELOG werden Änderungen an der Oberfläche festgehalten. Weitere Clients: AGENTS.md.

Bitten Sie Ihren Assistenten: „Listen Sie mit den netbox-Tools die ersten 5 Sites auf.“

Erstellen des Tokens

NetBox → Ihre Benutzermenü → API Tokens → Add a token.

• Lassen Sie Write enabled deaktiviert, es sei denn, der Assistent sollen Infrastrukturdatensätze ändern. Das ist die einzige Schreibkontrolle (siehe Schreibzugriff).

• Setzen Sie ein Ablaufdatum.

• Beschränken Sie die Objektberechtigungen des Tokens auf das, was der Assistent tatsächlich benötigt.

Related MCP server: NetBox MCP Server - Read & Write Edition

Zusätzlich den Skill installieren

Der Schnellstart oben installiert nur die Tools. Der Skill netbox-modeling installiert abschließende das kundige, obene sie – die Reihenfolge beim Aufbau, erforderliche Felder, veraltete Modelle und einen Plan, den Sie bestätigen, bevor irgendetwas geschrieben wird.

docs/installing-the-skill.md ist die Seite pro Oberfläche, mit exakten Pfaden und Konfigurationsblöcken für alle drei Stellen, an denen this Server läuft:

• Claude (Desktop, Code, Cowork) – ein Schritt für beide Hälften: /plugin marketplace add ZenixSolutions/netbox-mcp-server, dann /plugin install netbox-mcp@zenix-solutions. Das Plugin bringt die Server-Konfiguration und den Skill mit und fragt nach URL und Token.

• ChatGPT desktop (ein Codex-Host) – TOML unter ~/.codex/config.toml, Skill in ~/.agents/skills/.

• Grok Build (xAI-lokaler Agent) – TOML unter ~/.grok/config.toml, Skill in ~/.grok/skills/; er liest auch das oben genannte Claude-Plugin ohne jede Konfiguration.

Diese Seite behandelt auch, was sich selbst aktualisiert und was nicht – kurz: Claude-...; nur Claude-Plugins, bei Sitzungsbeginn. Sonst nichts.

Die fünf Tools

Der vorgesehene Weg für eine Änderung ist netbox_discover → netbox_describe → netbox_write. netbox_global_search ist die Abkürzung daran vorbei: Ein einzelnes, benanntes Objekt zu ermitteln, kostet einen einzigen Aufruf statt drei. Ein lesender Zugriff, bei dem der Typ schon bekannt ist – dcim.device, ipam.prefix – ist nur einer Aufruf an netbox_read.

Objekttyp-Schlüssel sind <app>.<model>, im Singular. Plugin-Modelle sind plugins.<plugin>.<model> und nicht erraten, wofür netbox_discover da ist.

Einige Verhaltensmöglichkeiten sind und es:

• Ein falscher Objekttyp oder Filtername wird von der Lokal abgelehnt, wobei die naheliegenden oder gültigen Filternamen Ergebnis sind. NetBox selbst beantwortet einen unbekannten Abfrageparameter mit 200 und der gesamten ungefilterten Sammlung. Deshalb lehnt der Server unbekannte Filter ab, statt sie durchzureichen.

• netbox_write validiert data gegen das Schema der Instanz, bevor etwas gesendet wird. Eine Ablehnung liefert dieselbe Beschreibung, die netbox_describe liefern würde.

• update ist eine partielle Schreibweise. Nur die in data vorhandenen Felder ändern sich.

• delete verlangt, dass confirm dem aktuellen display-Wert des Objekts entspricht. Lesen Sie das Objekt zuerst, kopieren Sie display, und geben Sie es zurück. NetBox führt kaskadernde Löschungen aus: Das Entfernen einer Site kann die zugehörigen Racks, Geräte und Prefixe entfernen. Das kann nicht rückgängig gemacht werden.

• netbox_read und netbox_global_search geben standardmäßig Markdown oder auf Wunsch JSON zurück. Listen verwenden standardmäßig Seiten von 50 Einträgen (maximal 1000) und melden total, has_more und next_offset; Antworten über 25.000 Zeichen werden zusammen mit dem Offset abgeschnitten, an dem die Fortsetzung folgt.

Schichtung kostet Round-Trips. Ein triviales Lesen, das ein einziger netbox_read-Aufruf beantwortet, wurde mit vier Aufrufen beobachtet, eine Namenssuche mit zehn. Siehe docs/reference/eval-model-in-loop.md und docs/reference/eval-results.md. Was sie einbringt, ist eine tools/list, die in ein Kontextfenster passt.

Die Begründung steht in RFC-003.

Konfiguration

Drei Umgebungsvariablen. Mehr gibt es nicht.

Das OpenAPI-Dokument der Instanz wird einmal, einmalig abgerufen und unter $XDG_CACHE_HOME/netbox-mcp (oder ~/.cache/netbox-mcp) auf Scheibe zwischengespeichert, abhängig von der NetBox-Version und der installierten Plugin-Liste aus /api/status/. Ein NetBox-Upgrade oder das Hinzufügen eines Plugins macht den Cache und wird nie schwerwiegend weg, denn ein fehlerhafter Cache ist nie fatally.

Schreibzugriff

Der Schreibzugriff wird über das NetBox-Token gesteuert, nicht über diesen Server. Es gibt keinen serverseitigen Nur-Lesen-Schalter, und das ist Absicht: Eine Umgebungsvariable, die das Write-Tool nur ausblendet, ist eine Empfehlung, während ein Token mit deaktiviertem write_enabled und eingeschränkten Objektberechtigungen von NetBox durchgesetzt wird – dort kann kein Tool-Argument es erreichen.

Erteilen Sie jedem, der keine Datensätze ändern muss, ein reines Lesen-Token. Wenn eine Schreiboperation abgelehnt wird, antwortet NetBox mitange 403, und der Fehlertext des Server nennt die wahrscheinliche Ursache – einschließlich des write_enabled-Flags des Tokens.

Weitere Hinweise für den sicheren Betrieb, um konkreten Prompt-Injection-Risiko: SECURITY.md.

Kommandozeilen-Oberfläche

Der Binarb extern in normally by a client, but there are four Kommandos to verify an installation. Ersetzen Sie den Befehl node dist/index.js für netbox-mcp, when Sie aus einem Klon gebaut haben.

--check ist das Kommando zur Diagnose eines Konfigurationsproblems. --help liefert das Ergebnis, bevor irgendetwas der Konfiguration gelesen wird, und gibt daher immer dieselbe Ausgabe aus, ob Ihre Anmeldedaten korrekt, falsch oder gar nicht vorhanden sind – ein Konfigurationsfehler kann nie sichtbar werden.

# Is the configuration usable? Names the offending variable and exits 78 if not.
NETBOX_URL=https://netbox.corp.com NETBOX_TOKEN="$NETBOX_TOKEN" netbox-mcp --check
# -> ok: netbox-mcp-server v0.2.0 configured for https://netbox.corp.com

# Does the binary work at all? Needs no credentials and makes no network calls.
netbox-mcp --list-tools
# -> netbox_global_search / netbox_discover / netbox_describe / netbox_read / netbox_write
#    5 tools registered.        (on stderr)

# Do the credentials work against NetBox itself?
curl -sS -H "Authorization: Token $NETBOX_TOKEN" \
  "$NETBOX_URL/api/dcim/sites/?limit=1" | head -c 200

Heben Sie das Token in einer Shell-Variable auf, statt es in ein Kommando zu tippen: Kommandozeilen landen in der Shell-Historie und sind in ps für jeden Prozess auf der Maschine sichtbar.

Kompatibilität und Einschränkungen

Die ehrliche Quelle ist docs/compatibility.md. In kurz:

• Vertragsüberprüft gegen NetBox 4.6.0 mit netbox_inventory 2.6.0 – 435 Checks, 0 Defekte. Das ist eine einzige Instanz, also ein Indizienbeweis, kein unterstützter Bereich. Antworten sehen je nach NetBox-Version unterschiedlich aus; bitte nennen Sie Ihre Version in jedem Fehlerreport. Das Kompatibilitätsdokument erklärt, wie Sie die Suite gegen Ihre eigene Instanz mit eine einem Read-Only-Token ausführen und was zurückmelden.

• Nur stdio. Es gibt keinen HTTP-Transport; Clients, die nur HTTP sprechen (ChatGPT-Konnektoren, Grok-Konnektoren), können nicht verwendet werden.

• Ein Plugin wurde verifiziert. Andere wurden noch nie probiert.

• Bekannte Einschränkungen – die Round-Trip-Kosten, der Argumentname device_id, keine Datei-Uploads, kein GraphQL – sind dort aufgeführt und werden nicht hier.

Aus einem Klon bauen

Für Mitwirkende und für Maschinen ohne Zugang zur npm-Registry:

git clone https://github.com/zenixsolutions/netbox-mcp-server.git
cd netbox-mcp-server
npm ci
npm run build
node dist/index.js --check     # exits 0 when NETBOX_URL and NETBOX_TOKEN are usable

Führen Sie npm ci in einer Shell aus, in der kein NETBOX_TOKEN exportiert ist: Es führt die Installationsskripte jedes Pakets im Abhängigkeitsbaum aus, und jedes davon erbt Ihre Umgebung.

Verwenden Sie dann dieselbe Client-Konfiguration wie oben, wobei command auf den absoluten Pfad aus command -v node gesetzt ist und args auf den absoluten Pfad von dist/index.js:

"netbox": {
  "command": "/opt/homebrew/bin/node",
  "args": ["/Users/YOU/netbox-mcp-server/dist/index.js"],
  "env": { "NETBOX_URL": "...", "NETBOX_TOKEN": "..." }
}

Tilden (~) werden von MCP-Clients nicht erweitert — beide Pfade müssen absolut sein.

Fehlerbehebung

Der mit Abstand häufigste Fehler: spawn npx ENOENT / spawn node ENOENT in einem GUI-Client. Claude Desktop wird aus dem Finder gestartet und liest Ihre ~/.zshrc nie ein, weshalb ein von nvm/fnm/asdf/Volta/Homebrew installiertes npx oder node für den Client unsichtbar ist. Tragen Sie den absoluten Pfad aus command -v npx (oder command -v node) in die Konfiguration ein, nicht den bloßen String "npx".

Der zweithäufigste Fehler: Missing required environment variable .... Führen Sie --check mit denselben Variablen aus, die die Konfiguration setzt — es benennt die Variable und beendet sich mit Code 78.

Claude Desktop protokolliert für jeden Server separat:

tail -f ~/Library/Logs/Claude/mcp-server-netbox.log

Die vollständige Tabelle der Symptome und Lösungen: AGENTS.md.

Entwicklung

npm run dev           # tsx watch src/index.ts
npm run build         # tsc -> dist/
npm run typecheck     # tsc --noEmit, sources + tests
npm run lint          # eslint
npm run format:check  # prettier --check
npm test              # vitest run
npm run test:contract # opt-in, against a live instance with a read-only token
npm run eval          # opt-in, evals/

src/
  index.ts            entry point; argv parsing (--help/--version/--check/--list-tools)
  server.ts           server construction and introspection
  config.ts           env parsing / validation
  constants.ts        character limits, page sizes, env var names
  client.ts           axios-based NetBox client
  errors.ts           NetBox API error formatting
  formatting.ts       markdown rendering + pagination payload
  schema/             fetch, cache and interpret the instance's /api/schema/
  schemas/common.ts   shared Zod schemas
  tools/layered/      the five tools: search, discover, describe, read, write
skills/
  netbox-modeling/    agent skill, versioned with the tool contract it names
scripts/
  check-changelog.mjs release guard: CHANGELOG has a section for the current version

Der Beschreibungstext jedes Tools liegt neben seiner Implementierung in src/tools/layered/*.ts — dieser Text ist die Schnittstelle, die die meisten Modelle tatsächlich sehen, und wird als solche überprüft.

Mitwirken

Issues und Pull-Requests sind willkommen — siehe CONTRIBUTING.md.

Sicherheitslücken sollten privat gemeldet werden, nicht als öffentliche Issues. Siehe SECURITY.md.

Haftungsausschluss

Dies ist ein unabhängiges, von der Community gepflegtes Projekt. Es ist weder mit NetBox Labs noch mit dem NetBox-Open-Source-Projekt verbunden, wird von diesen weder befürwortet noch unterstützt. „NetBox“ ist eine Marke des jeweiligen Eigentümers.

Wird ohne Gewährleistung („as-is“) unter der MIT-Lizenz bereitgestellt. Sie sind dafür verantwortlich, was ein KI-Assistent mit den Zugangsdaten tut, die Sie ihm geben — lesen Sie SECURITY.md, bevor Sie ein Token mit Schreibberechtigung für eine NetBox-Produktionsinstanz ausstellen.

Lizenz

MIT — siehe LICENSE.