# TheBoringMCP_netbox

MCP-Server (Model Context Protocol) mit **Vollzugriff auf [NetBox](https://github.com/netbox-community/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](docs/NETBOX_SETUP.md)
- Ein NetBox-API-Token mit Schreibrechten
- Docker **oder** Python ≥ 3.10

## Schnellstart mit Docker

1. Repository klonen:
   ```bash
   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:
   ```bash
   docker compose up -d --build
   ```
4. Prüfen:
   ```bash
   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:

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

**stdio (lokal, ohne Docker):**

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

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

```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)

| Variable | Standard | Beschreibung |
|---|---|---|
| `NETBOX_URL` | – (Pflicht) | Basis-URL der NetBox, ohne `/api` |
| `NETBOX_TOKEN` | – (Pflicht) | API-Token. `nbt_…` wird als `Bearer`, alles andere als `Token` gesendet |
| `NETBOX_VERIFY_SSL` | `true` | TLS-Zertifikat prüfen (bei selbstsignierten Zertifikaten `false`) |
| `NETBOX_READ_ONLY` | `false` | `true` sperrt alle schreibenden Aufrufe |
| `NETBOX_TIMEOUT` | `30` | Timeout je Request in Sekunden |
| `MCP_TRANSPORT` | `stdio` (Docker: `streamable-http`) | `stdio`, `streamable-http` oder `sse` |
| `MCP_HOST` / `MCP_PORT` | `0.0.0.0` / `8000` | Bind-Adresse für HTTP-Transport |
| `MCP_API_KEY` | leer | Schützt den HTTP-Endpunkt (`Authorization: Bearer …` oder `X-API-Key`). `/health` bleibt offen |
| `LOG_LEVEL` | `INFO` | Log-Level |

## Tools

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

| Tool | Zweck |
|---|---|
| `netbox_status` | Verbindung testen, NetBox-Version und Plugins |
| `netbox_list_endpoints` | Apps und Endpunkte der API anzeigen |
| `netbox_options` | Schema/Pflichtfelder eines Endpunkts |
| `netbox_list` | Objekte auflisten (Filter, Felder, Sortierung, Pagination, `all_pages`) |
| `netbox_get` | Einzelnes Objekt per ID |
| `netbox_create` | Objekt(e) anlegen (einzeln oder als Liste) |
| `netbox_update` | Objekt per PATCH ändern |
| `netbox_bulk_update` | Mehrere Objekte auf einmal ändern |
| `netbox_delete` / `netbox_bulk_delete` | Objekt(e) löschen |
| `netbox_get_or_create` | Idempotent anlegen |
| `netbox_search` | Volltextsuche über die wichtigsten Objekttypen |
| `netbox_changelog` | Letzte Änderungen (Change-Log) |
| `netbox_api_call` | Roher API-Zugriff (z. B. Config-Rendering, Plugin-Endpunkte) |

**Komfort-Tools**

| Tool | Zweck |
|---|---|
| `netbox_create_site` | Standort anlegen |
| `netbox_create_device` | Gerät anlegen; Site, Rolle, Hersteller, Gerätetyp werden bei Bedarf automatisch erzeugt |
| `netbox_create_interface` | Interface an einem Gerät |
| `netbox_connect_interfaces` | Kabelverbindung zwischen zwei Interfaces |
| `netbox_device_overview` | Gerät inkl. Interfaces und IPs |
| `netbox_create_vrf` / `netbox_create_vlan` / `netbox_create_prefix` | IPAM-Objekte anlegen |
| `netbox_create_ip_address` | IP anlegen, optional Interface zuweisen und als Primär-IP setzen |
| `netbox_available_ips` / `netbox_allocate_ip` | Freie IPs anzeigen bzw. nächste freie IPs reservieren |
| `netbox_available_prefixes` | Freie Unternetze anzeigen bzw. nächstes freies Unternetz anlegen |
| `netbox_create_virtual_machine` | VM anlegen (Cluster wird bei Bedarf erzeugt) |

## 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

| Meldung | Ursache |
|---|---|
| `NETBOX_URL ist nicht gesetzt` | Umgebungsvariablen fehlen |
| `Verbindung zu NetBox fehlgeschlagen` | URL/Netzwerk prüfen; im Container nicht `localhost` für NetBox verwenden |
| `403 … Authentication credentials were not provided` / `401` | Token falsch, abgelaufen oder ohne Schreibrechte |
| `400 …` mit Feldnamen | Validierungsfehler von NetBox – Schema mit `netbox_options` ansehen |
| SSL-Fehler | `NETBOX_VERIFY_SSL=false` bei selbstsignierten Zertifikaten |

## Lizenz

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