TheBoringMCP_netbox

MCP-Server (Model Context Protocol) mit Vollzugriff auf NetBox. Ein MCP-Client kann damit Standorte, Netzwerke, VLANs, IP-Adressen, Geräte, Interfaces, Kabel und VMs anlegen, auslesen, ändern und löschen – ohne dass du NetBox selbst per Hand konfigurieren musst.

• 27 Tools: generische CRUD-Tools für jeden NetBox-Endpunkt + Komfort-Tools für typische Aufgaben

• Löst Namen/Slugs selbst in IDs auf und legt fehlende Grundobjekte (Site, Rolle, Hersteller, Gerätetyp, Cluster) bei Bedarf an

• Läuft lokal per stdio oder als Docker-Container per HTTP (streamable-http)

• Optionaler API-Key-Schutz und Read-only-Modus

• Unterstützt v2-Tokens (nbt_…, NetBox ≥ 4.5) und v1-Tokens

Voraussetzungen

• Eine laufende NetBox-Instanz (empfohlen ≥ 4.2; Prefixe nutzen scope_type/scope_id). NetBox selbst per Docker aufsetzen: siehe docs/NETBOX_SETUP.md

• Ein NetBox-API-Token mit Schreibrechten

• Docker oder Python ≥ 3.10

Related MCP server: netbox-mcp

Schnellstart mit Docker

1. Repository klonen:

   git clone https://github.com/theboringalex/TheBoringMCP_netbox.git
   cd TheBoringMCP_netbox

2. In docker-compose.yml die Werte direkt eintragen (es wird bewusst keine .env-Datei verwendet):

   • NETBOX_URL – URL deiner NetBox, z. B. http://192.168.1.50:8080

   • NETBOX_TOKEN – dein API-Token

   • MCP_API_KEY – ein langer Zufallswert zum Schutz des MCP-Endpunkts (openssl rand -hex 32)

3. Starten:

   docker compose up -d --build

4. Prüfen:

   curl http://localhost:8000/health        # -> ok

Der MCP-Endpunkt ist danach unter http://<host>:8000/mcp erreichbar. Läuft NetBox im selben Docker-Host, kann der Container dem NetBox-Netzwerk beitreten (auskommentierter Block in docker-compose.yml) und NETBOX_URL auf http://netbox:8080 zeigen.

Als MCP-Client einbinden

HTTP (Docker-Variante) – URL http://<host>:8000/mcp, Header Authorization: Bearer <MCP_API_KEY>. Beispiel mit Claude Code:

claude mcp add --transport http theboringmcp-netbox http://<host>:8000/mcp \
  --header "Authorization: Bearer <MCP_API_KEY>"

stdio (lokal, ohne Docker):

python3 -m venv .venv
.venv/bin/pip install -r requirements.txt

Client-Konfiguration (z. B. claude_desktop_config.json):

{
  "mcpServers": {
    "TheBoringMCP_netbox": {
      "command": "/pfad/zu/TheBoringMCP_netbox/.venv/bin/python",
      "args": ["/pfad/zu/TheBoringMCP_netbox/server.py"],
      "env": {
        "NETBOX_URL": "http://192.168.1.50:8080",
        "NETBOX_TOKEN": "nbt_xxxxxxxxxxxx.yyyyyyyyyyyyyyyyyyyyyyyy"
      }
    }
  }
}

Konfiguration (Umgebungsvariablen)

Tools

Allgemein / generisch (funktionieren mit jedem Endpunkt, auch Plugins)

Komfort-Tools

Beispiele für Anfragen

• „Lege den Standort Zentrale an und darin die Netze 10.10.10.0/24 (Server, VLAN 10) und 10.10.20.0/24 (Clients, VLAN 20).“

• „Erstelle einen Switch sw-core-01 (Hersteller Ubiquiti, Typ USW-Pro-48) am Standort Zentrale und gib ihm die nächste freie IP aus 10.10.10.0/24 als Primär-IP.“

• „Zeige mir alle Geräte mit Status offline und alle freien IPs in 10.10.20.0/24.“

• „Verbinde Port 1 von sw-core-01 mit Port 48 von sw-access-02 per Cat6a.“

Sicherheit

• Der Server hat die Rechte des verwendeten NetBox-Tokens. Für reine Auswertungen ein Token ohne „Write enabled“ oder NETBOX_READ_ONLY=true verwenden.

• MCP_API_KEY immer setzen, sobald der HTTP-Port im Netzwerk erreichbar ist. Für Zugriff über das Internet einen Reverse-Proxy mit TLS davorschalten.

• Löschvorgänge sind unwiderruflich (nachvollziehbar nur im NetBox-Change-Log).

• Die Token-Werte stehen in der docker-compose.yml – diese Datei nicht öffentlich einchecken, nachdem echte Werte eingetragen wurden.

Fehlersuche

Lizenz

MIT – siehe LICENSE. NetBox ist ein Projekt der NetBox Community (Apache-2.0); dieses Repository steht in keiner offiziellen Verbindung dazu.