netbox-mcp-server

Un servidor Model Context Protocol que permite a un asistente de IA leer — y, si su token lo permite, escribir — en su instancia de NetBox: DCIM, IPAM, circuits, virtualización, tenancy, energía y cualquier plugin que esa instancia tenga instalado.

Escrito en TypeScript sobre el SDK oficial @modelcontextprotocol/sdk. Se ejecuta localmente a través de stdio como subproceso de un cliente compatible con MCP (Claude Desktop, Claude Code, Cursor, Codex).

Cinco herramientas, no varios cientos. Los tipos de objeto, campos, filtros y valores de enumeración no están codificados de forma fija; se derivan en tiempo de ejecución del documento /api/schema/ de la propia instancia, de modo que la superficie describe su NetBox, incluidos plugins y campos personalizados. Una respuesta de tools/list ocupa unos 12.000 caracteres de descripciones y esquemas, aproximadamente 3.000 tokens.

¿Instalando esto? Pegue esto en Claude, ChatGPT o cualquier asistente que pueda navegar y ejecutar comandos:

Lea https://raw.githubusercontent.com/zenixsolutions/netbox-mcp-server/main/AGENTS.md y sígalo para instalar el servidor NetBox MCP en mi Mac.

AGENTS.md es un runbook paso a paso escrito para que un asistente de IA lo ejecute sin adivinanzas. Los humanos pueden usar el Inicio rápido que sigue.

Inicio rápido

No hay nada que clonar ni compilar. Su cliente MCP lanza el servidor con npx, que descarga el paquete publicado la primera vez.

Necesita:

• Node.js >= 20.11 (node --version). Node 18 está en fin de vida y no se admite.

• Un token de API de NetBox — consulte Creación del token abajo.

Claude Desktop

Edite ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) o %APPDATA%\Claude\claude_desktop_config.json (Windows). Añada la entrada netbox al objeto mcpServers que ya tiene; no reemplace el archivo.

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

Use la ruta absoluta de command -v npx como command. Claude Desktop se inicia desde el Finder y nunca carga su perfil de shell, por lo que un "npx" sin ruta — igual que un "node" sin ruta — suele fallar con spawn npx ENOENT. Cierre Claude Desktop por completo (Cmd-Q) y vuélvalo a abrir tras editar la configuración.

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

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

No ponga el token en ~/.zshrc ni en ningún otro perfil de shell. Pertenece a la configuración del cliente y no a otro sitio.

Fije la versión — "@zenixsolutions/netbox-mcp@0.2.0" — si no quiere que la superficie de herramientas cambie entre reinicios. Este proyecto está por debajo de 1.0.0, y el CHANGELOG es donde se registran los cambios de superficie. Otros clientes: AGENTS.md.

Luego pregunte a su asistente: "Usando las herramientas netbox, lista los primeros 5 sitios."

Creación del token

NetBox → su menú de usuario → API Tokens → Añadir un token.

• Deje Write enabled sin marcar a menos que el asistente vaya a cambiar registros de infraestructura. Este es el único control de escritura que existe (consulte Acceso de escritura).

• Establezca una fecha de expiración.

• Restrinja lo permisos de objeto del token a lo que el asistente realmente necesite.

Instalar también la skill

La guía rápida anterior instala las herramientas. La skill netbox-modeling instala el criterio que las impulsa — orden de construcción, campos obligatorios, modelos obsoletos y un plan que confirma antes de escribir nada.

docs/installing-the-skill.md es la página por superficie, con rutas exactas y bloques de configuración para los tres lugares donde se ejecuta este servidor:

• Claude (Desktop, Code, Cowork) — un paso para las dos mitades: /plugin marketplace add ZenixSolutions/netbox-mcp-server y luego /plugin marketplace install netbox-mcp@zenix-solutions. El plugin lleva la configuración del servidor y la skill, y pide la URL y el token.

• Escritorio de ChatGPT (un host de Codex) — TOML en ~/.codex/config.toml, skill en ~/.agents/skills/.

• Grok Build (el agente local de xAI) — TOML en ~/.grok/config.toml, skill en ~/.grok/skills/; además lee el plugin de Claude anterior sin ninguna configuración.

Esa página también cubre qué se actualiza solo y qué no — en resumen: los plugins de Claude sí, al inicio de la sesión; nada más lo hace.

Las cinco herramientas

El camino previsto para un cambio es netbox_discover → netbox_describe → netbox_write. netbox_global_search es el atajo para evitar ese camino: buscar un objeto con nombre cuesta una única llamada en vez de tres. Una lectura en la que ya se sabe el tipo — dcim.device, ipam.prefix — es una llamada a netbox_read.

Las claves de tipo de objeto son <app>.<model>, en singular. Los modelos de plugins son plugins.<plugin>.<model> y no se pueden adivinar; para eso está netbox_discover.

Algunos comportamientos que conviene conocer:

• Un tipo de objeto o nombre de filtro incorrecto se rechaza localmente, con candidatos cercanos o la lista de nombres de filtro válidos. NetBox responde con 200 y toda la colección sin filtrar ante un parámetro de consulta que no reconoce; por eso el servidor rechaza filtros desconocidos en lugar de pasarlos tal cual.

• netbox_write valida data contra el esquema de la instancia antes de enviar nada.** Un rechazo devuelve la descripción que netbox_describe habría dado.

• update es una escritura parcial. Solo cambian los campos presentes en data.

• delete requiere que confirm sea igual al valor actual de display del objeto. Lea primero el objeto, copie display y devuélvalo. NetBox borra en cascada: eliminar un sitio puede quitar sus racks, dispositivos y prefijos, y no se puede deshacer.

• netbox_read y netbox_global_search devuelven Markdown por defecto o JSON si se solicita. Las listas paginan de 50 en 50 (máximo 1000) e informan de total, has_more y next_offset; cualquier respuesta de más de 25.000 caracteres se trunca e indica el offset para reanudar.

Las capas cuestan viajes de ida y vuelta. Una lectura trivial que se responde con una sola llamada a netbox_read se ha visto que necesita cuatro, y una búsqueda de nombre, diez. Esto está medido, no estimado, y reformular las descripciones de las herramientas no lo solucionó — consulte docs/reference/eval-model-in-loop.md y docs/reference/eval-results.md. Lo que se obtiene a cambio es un tools/list que cabe en la ventana de contexto.

El razón de diseño está en RFC-003.

Configuración

Tres variables de entorno. No hay otras.

El documento OpenAPI de la instancia se descarga una vez y se conserva en disco en $XDG_CACHE_HOME/netbox-mcp (o ~/.cache/netbox-mcp), con clave según la versión de NetBox y el conjunto de plugins instalados de /api/status/. Actualizar NetBox o añadir un plugin invalida la caché; una caché que no se pueda leer o escribir nunca es fatal.

Acceso de escritura

El acceso de escritura lo controla el token de NetBox, no este servidor. No hay un interruptor de solo lectura en el servidor, y eso es deliberado: una variable de entorno que oculta la herramienta de escritura es una sugerencia, mientras que un token con write_enabled desmarcado y permisos de objeto limitados lo aplica NetBox, donde ningún argumento de herramienta puede llegar.

Emita un token de solo lectura para quien no necesite cambiar cualquier registro. Si una escritura es rechazada, NetBox responde con 403 y el texto de error del servidor señala la causa probable — incluido el indicador write_enabled del token.

Más información para operarlo de forma segura, incluido el riesgo de inyección de prompt con un token con escritura habilitada: SECURITY.md.

Superficie de línea de comandos

El binario normalmente lo ejecuta un cliente, pero tiene cuatro verbos para comprobar la instalación. Sustituya node dist/index.js si compiló desde un clon.

--check es el comando para diagnosticar una configuración. --help devuelve antes de de que se lea ninguna configuración, es decir, imprime el mismo resultado tanto si sus credenciales son correctas como incorrectas o inexistentes — nunca puede mostrar un error de configuración.

# 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

Guarde el token en una variable de shell en lugar de escribirlo directamente: las líneas de comando quedan en el historial del shell y son visibles en ps para todos los procesos de la máquina.

Compatibilidad y limitaciones

La fuente honesta es docs/compatibility.md. En resumen:

• Probada por contratos contra NetBox 4.6.0 con netbox_inventory 2.6.0 — 435 comprobaciones, 0 defectos. Eso es una sola instancia, lo que es evidencia, no un rango con soporte. La forma de las respuestas difiere entre versiones de NetBox; incluya la suya en cualquier informe de errores. El documento de compatibilidad explica cómo ejecutar la prueba contra su propia instancia con un token de solo lectura y qué enviar de vuelta.

• Solo stdio. No hay transporte HTTP remoto, por lo que los clientes que solo hablan HTTP (conectores de ChatGPT, conectores de Grok) no pueden usarlo.

• Un plugin ha sido verificado. Otros nunca se probaron.

• Limitaciones conocidas (coste de los viajes de ida y vuelta, el nombre de argumento device_id, ningún envío de archivos, sin GraphQL) se enumeran allí en lugar de duplicarse aquí.

Compilar desde clon

Para colaboradores, y para máquinas que no pueden acceder al registro de npm:

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

Ejecuta npm ci en una shell sin NETBOX_TOKEN exportado: ejecuta los scripts de instalación de cada paquete en el árbol de dependencias, y cada uno hereda tu entorno.

Luego usa la misma configuración de cliente que arriba, con command establecido a la ruta absoluta de command -v node y args establecido a la ruta absoluta de dist/index.js:

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

Las tildes (~) no son expandidas por los clientes MCP — ambas rutas deben ser absolutas.

Solución de problemas

El fallo más común con diferencia: spawn npx ENOENT / spawn node ENOENT en un cliente GUI. Claude Desktop se lanza desde Finder y nunca carga tu ~/.zshrc, por lo que un npx o node instalado por nvm/fnm/asdf/Volta/Homebrew es invisible para él. Pon la ruta absoluta de command -v npx (o command -v node) en la configuración, no la cadena simple "npx".

El segundo más común: Missing required environment variable .... Ejecuta --check con las mismas variables que establece la configuración — nombra la variable y sale con el código 78.

Claude Desktop registra cada servidor por separado:

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

Tabla completa de síntomas y soluciones: AGENTS.md.

Desarrollo

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

El texto de descripción de cada herramienta se encuentra junto a su implementación en src/tools/layered/*.ts — ese texto es la interfaz que la mayoría de los modelos realmente ven, y se revisa como tal.

Contribuciones

Se aceptan incidencias y pull requests — consulta CONTRIBUTING.md.

Las vulnerabilidades de seguridad deben informarse de forma privada, no como incidencias públicas. Consulta SECURITY.md.

Descargo de responsabilidad

Este es un proyecto independiente mantenido por la comunidad. No está afiliado, respaldado ni apoyado por NetBox Labs ni por el proyecto de código abierto NetBox. "NetBox" es una marca comercial de su respectivo propietario.

Se proporciona tal cual bajo la licencia MIT. Eres responsable de lo que un asistente de IA haga con las credenciales que le des — lee SECURITY.md antes de emitir un token con permisos de escritura para una instancia de NetBox en producción.

Licencia

MIT — consulta LICENSE.