netmiko-mcp
claude-project — netmiko MCP server + skill
Un proyecto listo para copiar que otorga a un agente de IA acceso de solo lectura a routers, switches y cortafuegos a través de SSH, mediante el Model Context Protocol.
Incluye dos piezas y el cableado entre ellas:
mcps/mcp_server_netmiko.py— un servidor MCP autocontenido. Diez herramientas, cada comando validado frente a una lista de permitidos/denegados definida por el operador, salida analizada en JSON conntc-templates, y un registro de auditoría de cierre por fallo de cada intento..claude/skills/netmiko/SKILL.md— la habilidad que enseña al agente cuándo usar esas herramientas, cómo son los dialectos de CLI por plataforma y cómo leer una denegación.
Nada de esto escribe en un dispositivo. La lista de permitidos es denegación por defecto: una vacía no permite nada, y el lado de denegación siempre prevalece sobre el de permitidos.
Todo lo que sucede se registra en un registro de auditoría, y netmiko.query_audit_trail permite responderlo en la conversación: "todo lo hecho en SW-CORE-01, por fecha", "las últimas 6 acciones", "qué comandos fueron denegados esta semana". Sin interfaz de usuario en este proyecto, esa herramienta es la única forma de leerlo.
Autores y procedencia
Este proyecto está escrito por Ed Scrimaglia — edgardo.scrimaglia@gmail.com, Octupus. El servidor, la habilidad, el modelo de configuración y la documentación son obra suya, escritos para el agente Niko y empaquetados aquí como proyecto independiente.
Comenzó como una bifurcación, y ese origen se reconoce en lugar de ocultarse: el punto de partida fue el trabajo de Kirk Byers, y el proyecto creció mucho más allá. Lo que está aquí ahora — el inventario respaldado por la fuente de verdad, la resolución de credenciales, las tres variantes de despliegue, la paginación de salida, el registro de auditoría, la habilidad y esta documentación — no proviene del repositorio original.
Los dos proyectos originales de Kirk Byers:
Netmiko — la librería SSH multiventor que hace la comunicación real con los dispositivos.
netmiko_mcp — el servidor MCP del que se bifurcó este. Una parte sobrevive en gran medida como estaba: el núcleo de seguridad (validación de comandos, manejo de globs, la asimetría permitidos/denegados), mantenido como un puerto fiel a propósito para que los parches del repositorio original aún puedan ser diferenciados. Esa fue una decisión de ingeniería, no un límite para el resto del trabajo.
Related MCP server: MCP-Telecom
Acerca de Niko
Este servidor fue escrito para Niko, el agente de IA Neural Intelligence Knowledge Orchestrator creado por Ed Scrimaglia en Octupus. Niko maneja un conjunto de servidores MCP — el servidor de fuente de verdad, este, Jira, envío de correos, creación de archivos y otros — para que un operador pueda hacer una pregunta en lenguaje natural y obtener respuesta desde el terreno: la SoT para lo que debería ser cierto, los propios dispositivos para lo que es.
Dentro de Niko, el mismo archivo se ejecuta de forma ligeramente diferente, y vale la pena saberlo porque explica algunas cosas en el código:
Los servidores se ejecutan sobre HTTP en loopback, un puerto cada uno, declarados en
mcps/mcp_config.jsonconurl/transport/local/env— la misma configuración de dos ejes descrita abajo, expresada en el formato propio de Niko.La instalación se realiza a través de la aplicación, no copiando archivos: la carga se valida, las dependencias se resuelven desde el propio código, y una instalación fallida se revierte en lugar de dejar medio servidor atrás.
Cada una de esas integraciones es una importación opcional con un fallback, por lo que niko nunca tiene que estar instalado. Hay cuatro, y esto es lo que cada una degrada cuando falla la importación:
Importación | Línea | Fallback independiente |
| 60 |
|
| 68 |
|
| 436 |
|
| 2709 | una función vacía que devuelve la carga útil sin cambios |
No se pierde nada que sea importante fuera de Niko: el manejador concurrente resuelve un problema de varios procesos y un archivo que no ocurre aquí, y el presupuesto de lista recorta cargas útiles largas para un agente que tiene su propia contabilidad de contexto. Un archivo, dos hogares, sin bifurcación.
Fedele es la fuente de verdad de Niko, por lo que las variables de SoT llevan el prefijo FEDELE_ incluso cuando apuntan a una instancia de NetBox.
Licencia
El código propio de este proyecto es MIT — consulte LICENSE.
Es un trabajo derivado, por lo que se aplican dos licencias y ambos archivos se incluyen:
Licencia | Archivo | |
Código, documentación y habilidad de este proyecto | MIT | |
Partes portadas desde | Apache-2.0 |
NOTICE contiene la atribución y la declaración de modificaciones que requiere Apache-2.0 §4(b). Netmiko es una dependencia MIT común: importada, no vendida, nada que redistribuir.
Diseño
claude-project/
├── .mcp.json # declares the server (project scope)
├── .env.example # → copy to .env with the SSH credentials
├── .claude/skills/netmiko/
│ └── SKILL.md # one directory per skill, file named SKILL.md
├── mcps/
│ └── mcp_server_netmiko.py # NOT at the root: the server reads ../.env
├── config/netmiko/
│ ├── commands.yml # allow/deny list — without it, a 16-command fallback applies
│ └── inventory.yml # inventory in netmiko_tools format
├── logs/ # netmiko-mcp.log + netmiko-audit.jsonl
├── mcpr/netmiko/ # created on demand (0700): large outputs
├── LICENSE LICENSE-APACHE-2.0 NOTICE
└── pyproject.tomlDos reglas que no son negociables:
La habilidad reside en
.claude/skills/<nombre>/SKILL.md. Claude Code no leeskills/netmiko.md: necesita el directorio y ese nombre de archivo exacto.El servidor reside en
mcps/, no en la raíz.PARENT_DIRes el padre del directorio que contiene el.py(mcp_server_netmiko.py:62), y de ahí proviene el.env. Con el servidor en la raíz, el.envse buscaría un nivel por encima del proyecto.
Ponerlo en marcha
uv venv --python 3.12
uv pip install -r <(uv pip compile pyproject.toml) # or: uv sync
cp .env.example .env && $EDITOR .env # SSH credentials
# .mcp.json needs no editing: its paths are project-relative
claude # approve the project serverDentro de la sesión: /mcp lista las 10 herramientas, /skills confirma que la habilidad se cargó. Primera comprobación, sin tocar la red:
¿qué política de comandos está aplicando el MCP de netmiko?
Las tres variantes
De dónde proviene el inventario y de dónde provienen las credenciales son dos ejes independientes. Eso es lo que genera tres despliegues a partir de un solo servidor — y la razón por la que el servidor nunca necesita ser modificado para moverse entre ellos: dos variables de entorno lo deciden.
Inventario | Credenciales | Lo que necesitas | Cuándo usarlo | |
A — SoT todo | Fedele | Fedele | Token API + clave Fernet | La SoT es autoritativa y ya contiene las credenciales del dispositivo |
B — Inventario SoT, credenciales locales | Fedele o NetBox |
| Token API | Tienes una SoT pero no su plugin de credenciales. El punto de partida habitual |
C — Autocontenido | YAML local |
| nada externo | Laboratorio, aire aislado, demo, o modo degradado cuando la SoT está caída |
netmiko.get_metadata informa cuál se está ejecutando realmente — nunca asumas desde el archivo de configuración:
{
"inventory": {"backend": "fedele", "scope_filter": {"tag": "lab"}, "available": true},
"credential_source": "env",
"device_types_in_inventory": ["cisco_ios", "huawei_vrp", "…"]
}A — Fedele como fuente de verdad, credenciales incluidas
El agente solicita un dispositivo por nombre; el servidor resuelve dirección, plataforma y credenciales contra la SoT en el momento de la llamada. Nada sobre el inventario reside en este proyecto: añade un dispositivo a la SoT y estará accesible en la siguiente llamada, sin necesidad de editar archivos ni reiniciar.
// .mcp.json → env
"NETMIKO_MCP_INVENTORY_TYPE": "fedele",
"NETMIKO_MCP_CREDENTIAL_SOURCE": "fedele",
"NETMIKO_MCP_FEDELE_GROUP_SOURCE": "tags", // tags | device_roles | sites
"NETMIKO_MCP_FEDELE_DEVICE_FILTER": "tag=lab", // the scope filter — read the warning
"NETMIKO_MCP_FEDELE_CACHE_TTL": "60"# .env
FEDELE_URL=https://fedele.example.com
FEDELE_TOKEN=<API token>
FEDELE_CREDENTIALS_KEY=<Fernet key of the fedele_credentials plugin>Archivos: ninguno es obligatorio. commands.yml es recomendado — sin él se aplica la política de fallback incorporada. No hay inventario local involucrado, ni NETMIKO_USERNAME / NETMIKO_PASSWORD; con credential_source=fedele, NETMIKO_SECRET es ignorado — la contraseña de enable también proviene de la SoT.
Cómo funciona la búsqueda de credenciales, tres saltos:
GET dcim/devices/?name=<name> → device.id
GET plugins/credentials/devicecredentials/?device=<id> → credential id
GET plugins/credentials/networkcredentials/<id>/ → username + encrypted password
decrypted locally with the Fernet keyCosas que vale la pena saber antes de elegir esta variante:
La clave Fernet es todo el perímetro de seguridad. Descifra las contraseñas de los dispositivos en la memoria del servidor. Trátala como las propias contraseñas.
Sin
FEDELE_CREDENTIALS_KEYel servidor aún arranca, y todas las herramientas devuelven el mismoError de inicioindicando la variable faltante. Falla de forma ruidosa, no silenciosa.Establece el filtro de alcance. Sin
NETMIKO_MCP_FEDELE_DEVICE_FILTERel inventario es todo el parque que la SoT conoce, que también es el conjunto completo de dispositivos a los que el agente puede acceder. El servidor registra una advertencia cuando falta; el filtro acepta sintaxis de consulta,tag=lab&status=active.Un dispositivo sin
primary_ip, sinplatform, o cuya plataforma no es undevice_typede Netmiko es excluido del inventario — las SoT también inventarizan cámaras, lectores de tarjetas y chasis. Las exclusiones se cuentan y reportan, para que el agente nunca afirme "estos son todos los dispositivos" sobre un subconjunto.Hay un cortacircuitos: después de un error de transporte o un 5xx, el cliente deja de llamar a la SoT durante 30 s. Un comando grupal contra 40 dispositivos con la SoT caída falla una vez, no cuarenta veces.
B — SoT para el inventario, credenciales en el .env
Idéntico a A con una variable cambiada:
"NETMIKO_MCP_CREDENTIAL_SOURCE": "env",# .env
FEDELE_URL=https://sot.example.com
FEDELE_TOKEN=<API token>
NETMIKO_USERNAME=<service account>
NETMIKO_PASSWORD=<password>
NETMIKO_SECRET=<enable password, if any device asks for it>Obtienes el inventario dinámico — la parte que se paga sola — sin el plugin de credenciales y sin la clave Fernet. Se utiliza una cuenta de servicio para todos los dispositivos.
NetBox, o cualquier SoT con forma de NetBox
El backend de inventario habla el dialecto REST de NetBox, por lo que NetBox mismo funciona en esta variante, sin modificaciones:
Lo que el backend llama | Lo que lee |
| la lista de dispositivos, filtrada por el filtro de alcance y paginada |
| el que |
| el host SSH, máscara eliminada |
| el |
Apunta FEDELE_URL a la instancia de NetBox (se añade /api si lo omites) y FEDELE_TOKEN a un token de API de NetBox — el cliente se autentica con el encabezado Authorization: Token … que NetBox espera. Las variables mantienen el prefijo FEDELE_; eso es un legado de nomenclatura, no un requisito del producto.
El único requisito que NetBox no cumple por defecto: platform.name debe ser exactamente un device_type de Netmiko — cisco_ios, arista_eos, huawei_vrp, juniper_junos. Una plataforma llamada "Cisco IOS 15.2" no es un device_type, por lo que todos los dispositivos que la lleven son excluidos del inventario. O renombra las plataformas en NetBox o acepta las exclusiones, que son reportadas.
Las credenciales son la parte que NetBox no cubre: los endpoints plugins/credentials/… pertenecen al plugin de Fedele. Con NetBox simple, la variante A no está disponible — quédate en B.
C — Autocontenido: sin SoT en absoluto
Todo reside en este proyecto. No se contacta ningún servicio externo, nunca.
// .mcp.json → env
"NETMIKO_MCP_INVENTORY_TYPE": "yaml",
"NETMIKO_MCP_CREDENTIAL_SOURCE": "env",
"NETMIKO_MCP_INVENTORY_FILE": "/abs/path/claude-project/config/netmiko/inventory.yml"# .env
NETMIKO_USERNAME=<service account>
NETMIKO_PASSWORD=<password>
NETMIKO_SECRET=<enable password, if any device asks for it>Archivos: inventory.yml es obligatorio aquí — es el único lugar donde existen los dispositivos. commands.yml sigue siendo recomendado, no obligatorio. El inventario tiene el formato de netmiko_tools — un mapeo plano de nombre a datos de conexión, más claves de grupo:
CORE-RTR-01:
device_type: cisco_xr # must be a Netmiko device_type, verbatim
host: 192.0.2.11
CORE-SW-01:
device_type: arista_eos
host: 192.0.2.21
core: # a group is a list of device names
- CORE-RTR-01
- CORE-SW-01El archivo que incluye este proyecto son datos de ejemplo: 12 dispositivos ficticios en los rangos de documentación RFC 5737, 7 grupos y plataformas elegidas para que todos los dialectos CLI que menciona la lista de permitidos estén representados. Sustitúyelo por tu propio parque.
Este es el sabor con el que este proyecto viene configurado, y también es el modo degradado: si el SoT cae, dos variables y un reinicio mueven un despliegue de sabor A o sabor B aquí. Vale la pena ensayarlo antes de que lo necesites.
El coste es que el archivo se queda obsoleto. scripts/export_inventory.py en el repositorio padre lo regenera desde el SoT; ejecútalo con una programación. Un inventario de respaldo con direcciones de hace seis meses es peor que no tener respaldo, porque te enteras durante la operación.
Lo que se mantiene igual en los tres
La política de comandos, la pista de auditoría, la paginación de salida y la superficie de herramientas no cambian entre sabores. El contrato orientado al agente es idéntico, por eso la habilidad no necesita una variante por sabor.
commands.yml es recomendado, no obligatorio
El servidor funciona sin él. Si el archivo falta, no deniega todo y no se niega a arrancar: un fallback integrado de 16 comandos de solo lectura toma el control — show version, show ip interface brief, display version y sus equivalentes Junos/VRP. Esto es deliberado. Una política vacía denegaría cada comando mientras el servidor se reporta como saludable, lo que un operador leería como "el dispositivo rechazó" en lugar de "nadie escribió una política". El fallback se anuncia al inicio, netmiko.get_command_policy reporta policy_source: "fallback", y cada intento auditado lleva la fuente.
Así que el archivo es una decisión de política, no un paso de instalación: el fallback te permite ejecutar el servidor en el primer intento, y escribes commands.yml cuando quieres la política de tu propio parque en lugar de un valor predeterminado conservador. Lo que no puedes hacer es tener una política que no elegiste y no saberlo — el servidor dice cuál está en vigor cada vez que se le pregunta.
El archivo .mcp.json
.mcp.json en la raíz del proyecto declara los servidores MCP para este proyecto. Claude Code pide aprobación la primera vez que ve el archivo, y el archivo está pensado para ser confirmado: es cómo todo el equipo obtiene el mismo servidor.
Existen otros dos ámbitos para la misma definición de servidor:
Ámbito | Dónde reside | Quién lo ve |
|
| cualquiera que abra el proyecto (tras aprobarlo) |
|
| todos los proyectos de ese usuario, en esa máquina |
|
| solo ese usuario, solo en ese proyecto |
claude mcp add --scope project netmiko -- /path/to/python /path/to/server.py
escribe la entrada project por ti; editar el JSON a mano es equivalente.
Forma del archivo
{
"mcpServers": { // ← the top-level key. Not "servers", not "mcp".
"netmiko": { // ← the server name; it becomes the tool prefix
... // mcp__netmiko__<tool>
}
}
}El nombre del servidor no es cosmético: Claude Code expone cada herramienta como
mcp__<nombre-servidor>__<nombre-herramienta>. Con el nombre netmiko y la herramienta
netmiko.get_metadata que el servidor registra, la herramienta que Claude realmente ve
es mcp__netmiko__netmiko.get_metadata. Ejecuta /mcp para leer los nombres exactos
antes de escribirlos en una lista allowed-tools o en una regla de permisos.
Referencia de campos
Campo | Transporte | Significado |
| ambos |
|
| stdio | el ejecutable a lanzar. Ruta absoluta — no asumas un directorio de trabajo |
| stdio | lista de argumentos, cada elemento separado |
| stdio | entorno para el proceso hijo. Se fusiona sobre el heredado |
| http / sse | URL completa del endpoint, incluida la ruta |
| http / sse | cabeceras extra de la solicitud, típicamente |
Los valores soportan expansión de entorno: ${VAR} y ${VAR:-default}. Útil para
mantener un token fuera del archivo confirmado:
"headers": { "Authorization": "Bearer ${NETMIKO_MCP_TOKEN}" }Transporte 1 — stdio (el que usa este proyecto)
Claude Code lanza el servidor como un proceso hijo y habla JSON-RPC a través de su stdin/stdout. Nada escucha en un puerto, nada es accesible desde la red, y la vida del proceso es la de la sesión. Este es el valor predeterminado correcto para un servidor que contiene credenciales SSH.
{
"mcpServers": {
"netmiko": {
"type": "stdio",
"command": "${CLAUDE_PROJECT_DIR:-.}/.venv/bin/python",
"args": ["${CLAUDE_PROJECT_DIR:-.}/mcps/mcp_server_netmiko.py"],
"env": {
"NETMIKO_MCP_INVENTORY_TYPE": "yaml",
"NETMIKO_MCP_INVENTORY_FILE": "${CLAUDE_PROJECT_DIR:-.}/config/netmiko/inventory.yml",
"NETMIKO_MCP_COMMAND_FILE": "${CLAUDE_PROJECT_DIR:-.}/config/netmiko/commands.yml",
"NETMIKO_MCP_CREDENTIAL_SOURCE": "env",
"NETMIKO_MCP_SAVE_OUTPUT_DIR": "${CLAUDE_PROJECT_DIR:-.}/mcpr/netmiko",
"NETMIKO_MCP_AUDIT_LOG_FILE": "${CLAUDE_PROJECT_DIR:-.}/logs/netmiko-audit.jsonl",
"LOG_FILE": "${CLAUDE_PROJECT_DIR:-.}/logs/netmiko-mcp.log",
"LOG_LEVEL": "INFO"
}
}
}
}Dos cosas que pican:
Sin rutas codificadas, y el directorio de trabajo no es algo en lo que confiar.
${CLAUDE_PROJECT_DIR:-.}es lo que mantiene el archivo confirmable tal cual; la siguiente sección cuenta toda la historia, porque la lectura obvia es incorrecta.El servidor no debe escribir en stdout. stdout es el canal del protocolo, y una línea suelta ahí rompe la sesión. El registro va a stderr más el archivo rotatorio en
LOG_FILE(5 MB × 3, creado0600— enDEBUGeste archivo lleva la salida del dispositivo). Dentro de Niko la misma variable es manejada porMCPLoggingen su lugar.
De dónde viene ${CLAUDE_PROJECT_DIR:-.}
Dos cosas separadas en una cadena: una sintaxis y una variable.
La sintaxis. ${VAR} y ${VAR:-default} es sustitución de parámetros POSIX
("usa VAR; si no está definida o está vacía, usa default"), pero no interviene ningún shell
— un archivo JSON nunca pasa por uno. Claude Code implementa la expansión
por sí mismo cuando lee el archivo, en command, args, env, url y headers.
Es una convención de ese cliente, no parte de la especificación MCP: otro
cliente puede no implementarla (ver Agentes que no son Claude, donde
las rutas entonces tienen que ser literales), y VS Code tiene su propia ortografía,
${workspaceFolder}.
La variable. CLAUDE_PROJECT_DIR es establecida por Claude Code en la raíz del
proyecto, el mismo valor que reciben los hooks. Es estable — conceder
directorios de trabajo adicionales a mitad de sesión con --add-dir no la mueve.
La parte que es contraintuitiva, y la razón por la que :-. no es decoración:
Claude Code establece esa variable en el entorno del servidor que lanza,
no en el suyo propio. La expansión, sin embargo, ocurre antes del lanzamiento,
contra el entorno de Claude Code — donde la variable no existe. Un
${CLAUDE_PROJECT_DIR} desnudo se expandiría por tanto a nada y dejaría
/config/netmiko/inventory.yml, una ruta absoluta a la raíz del sistema de archivos.
Así que en un .mcp.json de ámbito de proyecto el valor predeterminado no es un fallback para algún caso extremo:
es el valor que se usa, cada vez. Lo que llega al proceso es
./config/netmiko/inventory.yml. La única excepción es una configuración MCP enviada por
un plugin — allí Claude Code sustituye la variable directamente y no se necesita ningún valor predeterminado.
Eso es lo que fuerza la mano del servidor. Un valor relativo se resolvería contra
el directorio de trabajo del proceso hijo, y el directorio de trabajo es elección del cliente,
no del proyecto. De ahí resolve_project_path(): cada ajuste de ruta relativa se
ancla a PARENT_DIR — el padre de mcps/, la misma raíz de la que viene .env —
cuando se cargan los ajustes. Una sesión lanzada desde cualquier lugar encuentra
config/netmiko/, y validate_startup() nombra el archivo absoluto cuando falta uno.
Una ~ sigue significando el home del operador, nunca un archivo dentro del proyecto.
La variable sigue siendo útil como la documentación pretende, leída desde
dentro del servidor (os.environ["CLAUDE_PROJECT_DIR"]), donde está establecida. Este
servidor no la necesita: PARENT_DIR se deriva de __file__ y por tanto no depende de ningún
cliente — la misma razón por la que el transporte HTTP, donde nadie establece esa
variable, no necesita un caso especial.
Fuente: Claude Code — MCP, secciones Add
a local stdio server y Environment variable expansion in .mcp.json.
Transporte 2 — HTTP (HTTP transmisible)
Claude Code lo soporta, y también cualquier otro cliente MCP. Es el transporte a usar cuando el servidor se ejecuta en otro lugar: otro host, un contenedor, un servicio compartido por varios agentes, o un agente que no es Claude.
El archivo del servidor siempre llama a mcp.run(transport="stdio") bajo su guarda
__main__, así que HTTP se sirve mediante la CLI de FastMCP en su lugar — sin cambio de código:
.venv/bin/fastmcp run mcps/mcp_server_netmiko.py \
--transport http --host 127.0.0.1 --port 8123
# endpoint: http://127.0.0.1:8123/mcp/Las variables NETMIKO_MCP_* ya no forman parte de la configuración del cliente:
el proceso del servidor lo inicias tú, por lo que pertenecen a su entorno (una exportación de shell,
una unidad systemd, un bloque environment: de un contenedor).
Lado del cliente:
{
"mcpServers": {
"netmiko": {
"type": "http",
"url": "http://127.0.0.1:8123/mcp/",
"headers": {
"Authorization": "Bearer ${NETMIKO_MCP_TOKEN}"
}
}
}
}O, equivalentemente, claude mcp add --transport http netmiko http://127.0.0.1:8123/mcp/.
--transport sse y "type": "sse" también funcionan; SSE es el transporte remoto
más antiguo y se mantiene para clientes que no han migrado a HTTP transmisible.
Seguridad. La CLI de FastMCP sirve esto sin autenticación alguna: quien alcance el puerto puede ejecutar comandos show contra cada dispositivo del inventario, usando las credenciales del entorno del servidor. Enlaza a
127.0.0.1para una prueba local, y para cualquier cosa compartida ponlo detrás de un proxy inverso que termine TLS y verifique la cabeceraAuthorization. El bloqueheadersde arriba es lo que el cliente envía; el proxy es quien debe verificarlo.
Agentes que no son Claude
El objeto mcpServers mostrado aquí es la forma de facto: Claude Code, Claude
Desktop, Cursor y Windsurf leen los mismos tres campos para stdio
(command / args / env) y los mismos dos para remoto (url / headers).
Copiar una entrada entre ellos normalmente funciona tal cual.
Diferencias conocidas que vale la pena comprobar antes de copiar:
VS Code usa
mcp.jsoncon una clave de nivel superior"servers"en lugar de"mcpServers", y quiere que"type"se indique explícitamente.Algunos clientes no implementan la expansión
${VAR}; allí el valor tiene que ser literal, lo cual es un argumento para el transporte HTTP más un proxy en lugar de un token pegado en un archivo confirmado.Un agente sin ningún archivo de configuración aún puede hablar directamente con el endpoint HTTP — la URL y la cabecera
Authorizationson todo el contrato.
El bloque env
Las entradas NETMIKO_MCP_* prevalecen sobre cualquier archivo de configuración YAML. Se establecen
explícitamente porque fuera de Niko no hay NikoPaths, por lo que los valores predeterminados
caen en ~/commands.yml y ~/.netmiko_mcp_tmp.
Cada ruta aquí puede escribirse relativa a la raíz del proyecto: el servidor ancla
los valores relativos a PARENT_DIR cuando se cargan los ajustes, por lo que el directorio de trabajo del
proceso lanzado nunca decide dónde vive el inventario o la pista de auditoría. Una
ruta absoluta o una ~ se toma tal cual.
Variable | Default | Propósito |
|
|
|
| (búsqueda de netmiko-tools) | ruta del inventario cuando el tipo es |
|
|
|
|
| qué define un grupo: |
| (ninguno) | filtro de alcance, |
|
| caché de resolución de SoT, en segundos |
|
| lista de permitidos/denegados |
|
| habilita tuberías en los comandos |
| (ninguno) |
|
|
| conexiones concurrentes en comandos de grupo |
|
| búfer para salidas grandes |
|
| número de líneas a partir del cual la salida se guarda en lugar de devolverse en línea |
| (véase el README principal) | registro de auditoría (JSON, cierre por fallo). Pida al agente que lo lea con |
|
| ruta a un archivo de configuración YAML que contiene estos mismos ajustes |
|
| registro operativo: siempre stderr, más este archivo rotatorio (5 MB × 3, |
Las credenciales no se configuran aquí. NETMIKO_USERNAME, NETMIKO_PASSWORD,
NETMIKO_SECRET y las variables FEDELE_* se leen desde
<project-root>/.env, para que nunca terminen en un archivo JSON confirmado.
Precedencia: lo que está en el bloque env prevalece sobre el .env, en silencio —
defina cada variable en un solo lugar.
Todas las demás variables están documentadas en el README del repositorio principal.
Comprobación de funcionamiento
claude mcp list # netmiko: ✓ connectedDentro de la sesión, /mcp lista las herramientas y /skills confirma que la habilidad se ha
cargado. Pregunte qué política está vigente y netmiko.get_command_policy indica el nombre del
archivo que está leyendo — o informa "fallback", lo que significa que nunca encontró el
archivo y se está ejecutando con los 16 comandos integrados.
Autor: Ed Scrimaglia edgardo.scrimaglia@gmail.com — última actualización: 2026-08-18.
Available Tools
10 toolsnetmiko.get_command_policyA
List the commands this server will accept, and where that policy comes from.
CALL THIS AFTER A REFUSAL, BEFORE RETRYING. A Security Error: Command ... is not permitted means the command is outside the operator's policy. Do not guess a
variant and do not abbreviate — read the policy here, pick a command that is
actually allowed, and if nothing fits, tell the user which command was refused
and what the allow list does cover.
Also useful when the user asks what they can run on this deployment.
ANSWERING "which commands are available for Juniper / Huawei / Cisco": the lists
are flat, because the operator writes one policy for the whole estate. Filter it
yourself by dialect — you know the CLIs, and device_types_in_inventory tells
you which platforms are actually present. show route* and show chassis* are
Junos, display * is Huawei VRP and HPE Comware, show ip route is Cisco-style,
and show version happens to work on several. Under the fallback,
allowed_commands_by_platform already carries that split, verbatim and exact —
use it as given instead of re-deriving it. Two rules when you answer:
Never list a command that is not in
allowed_commands. It will be refused.Say when the answer is empty: an allow list written for one vendor covers nothing on another, and that is the operator's doing, not a device fault.
policy_source says who wrote the policy in force:
"file" — the operator's allow/deny list, at
command_file."fallback" — no policy file exists on this deployment, so only a small built-in read-only set runs.
warningexplains it; relay that to the user, because every other refusal follows from it and looks like a device problem otherwise.
How the lists are read (getting this wrong wastes attempts, and every attempt is audited):
Deny wins over allow, always.
The allow list does NOT cover abbreviations:
show versiondoes not permitsh ver. Send full commands.The deny list DOES cover abbreviations of the same word count: a deny on
configurealso blocksconf.*is a glob and only ever appears at the end.cmd*swallows whatever follows;cmd *requires at least one more word and does not matchcmdon its own.Anything the allow list does not name is denied.
Returns:
str: JSON with policy_source, command_file, allowed_commands,
denied_commands, their counts, a rules object,
device_types_in_inventory, and — only under the fallback —
allowed_commands_by_platform and a warning.
Inputs: no named parameters. Returns: result
netmiko.get_metadataA
Return authoritative metadata about the Netmiko MCP server and its inventory.
MANDATORY — call this tool FIRST on EVERY user message that mentions, asks about, or relates to network devices, routers, switches, firewalls, show commands, device inventory or device groups, before any other netmiko tool and before answering from memory, system prompt, or RAG/FAQ.
It reports which inventory backend is active (Fedele or the local YAML file) and, for the local file, how old it is. That matters: operating from a stale local inventory can send a command to the wrong box.
This tool does NOT reach any network device. For "is the MCP alive" call netmiko.health_check. To actually query a device, use netmiko.send_show_command.
Returns:
str: JSON with version, author, description, inventory, capabilities,
command_policy and tool_routing. command_policy is "file" when the
operator's allow/deny list is in force and "fallback" when no policy file
exists — in that case a warning field says so, only a handful of
read-only commands will be accepted, and you must relay that warning to
the user instead of treating the denials as device failures.
Inputs: no named parameters. Returns: result
netmiko.health_checkA
Check whether the Netmiko MCP server itself is responsive and correctly configured.
IMPORTANT: If the user message involves network devices, call netmiko.get_metadata FIRST.
This checks the MCP server, NOT any network device and NOT the inventory backend reachability. "¿Está arriba el router X?" is not this tool — that requires actually running a command against the device with netmiko.send_show_command.
Returns:
str: JSON with available, version, inventory_backend,
credential_source and command_policy ("file" or "fallback").
When command_policy is "fallback" a warning field explains that
no policy file exists and only built-in read-only commands run;
report that warning to the user.
Inputs: no named parameters. Returns: result
netmiko.list_device_outputsA
List the output files already saved on disk for a device, group, or all devices.
IMPORTANT: If the user message involves network devices, call netmiko.get_metadata FIRST.
Outputs land here when save_output=True was used or when a command exceeded save_threshold. Read them with netmiko.read_device_output.
Inputs: device_or_group (required). Returns: result
netmiko.list_devicesA
List devices from the inventory, without credentials.
IMPORTANT: If the user message involves network devices, call netmiko.get_metadata FIRST.
Use this to discover exact device names before running a command. Device names are the only handle the other tools accept — never pass an IP address or a hostname you inferred.
Inputs: device_or_group. Returns: result
netmiko.list_groupsA
List every device group defined in the inventory.
IMPORTANT: If the user message involves network devices, call netmiko.get_metadata FIRST.
Groups are what netmiko.send_show_command_to_group accepts. Call this before assuming a group name exists — never invent one.
Returns:
str: JSON with groups (list of group-name strings) and count.
Inputs: no named parameters. Returns: result
netmiko.query_audit_trailA
Read the audit trail: what this server was asked to do, and what happened.
Answers questions about PAST activity — "everything done on SW-CORE-01", "the last 6 netmiko actions", "which commands were refused this week", "who touched that switch and with which credential". It reads the audit records only; it never opens a connection and never returns device output.
Every argument is a filter, combined with AND. Leave one empty to not filter on it. Translate what the user asked into these arguments — do not ask for everything and sift through it.
The audit trail rotates daily and this reads the rotated files too, but only
what is still on disk. files_scanned and oldest_available in the response
say how far back the answer actually reaches: if the period the user asked
about is older than that, say so instead of reporting "nothing happened".
matched is how many records satisfied the filters; returned is how many
came back in this call. When they differ, the response is one page — never
report returned as a total.
Calling this tool writes a tool_invocation record of its own — reading the
trail is itself auditable — but those records are hidden from the results by
default, so "the last 6 actions" is about the network and not about your own
questions. audit_queries_hidden says how many were left out.
Inputs: tool, event, limit, order, +10 more. Returns: result
netmiko.read_device_outputA
Read a previously saved output file for one device, with pagination.
IMPORTANT: If the user message involves network devices, call netmiko.get_metadata FIRST.
The response header states the line range and the total line count. When lines remain, a continuation hint gives the offset to use next. Do not report a total based on a page you have not finished reading.
Inputs: filename (required), device_name (required), limit, offset. Returns: result
netmiko.send_show_commandA
Connect to one network device over SSH and run a single show command.
IMPORTANT: If the user message involves network devices, call netmiko.get_metadata FIRST.
The command is validated against the operator's allow/deny list before execution. A rejection is NOT a bug and NOT something to work around: report it to the user and say which command was refused. Do not retry with an abbreviation — abbreviations are covered by the deny list, not by the allow list.
SYNTAX IS PER-PLATFORM. Netmiko drives 177 base device_types (416 with variants)
from 102 vendors and their CLIs are NOT interchangeable. Check the device's
device_type with netmiko.list_devices first and use that platform's syntax:
Cisco IOS/Arista/Juniper use show ..., Huawei VRP and HPE Comware use
display ..., MikroTik RouterOS uses /system resource print, F5 tmsh uses
list/show with its own grammar. Never translate a command from one family
to another by analogy, and never probe variants to see which one is accepted —
each attempt is audited and may be denied for a different reason.
Inputs: command (required), device_name (required), save_output, use_textfsm. Returns: result
netmiko.send_show_command_to_groupA
Run the same show command concurrently on every device of a group.
IMPORTANT: If the user message involves network devices, call netmiko.get_metadata FIRST.
The command is validated once before any connection is opened, so a denied command reaches no device at all. Per-device failures are returned per device: a partial result is normal and must be reported as partial, never summarised as if every device answered.
A GROUP MAY MIX PLATFORMS. The same command string is sent to every member, so a
group holding both Cisco IOS and Huawei VRP devices will fail on half of them
whatever you send — show version is invalid on VRP, display version is invalid
on IOS. Check device_type across the group with netmiko.list_devices first; if
the group is heterogeneous, issue one netmiko.send_show_command per platform
instead of forcing a single string onto all of them.
Inputs: command (required), device_or_group (required), save_output, use_textfsm. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 10 tools
Each tool targets a clear resource and action, and the descriptions explicitly define when each should be used. get_metadata and health_check overlap somewhat since both report server configuration details, but their distinct purposes are clearly explained.
Most names follow a consistent verb_noun pattern such as list_devices, send_show_command, and query_audit_trail. health_check is the main deviation, being a noun phrase rather than a verb-led name, but the overall pattern remains predictable.
10 tools is well within the ideal scope for a network automation server. Each tool earns its place by covering a distinct function: metadata, policy, health, inventory, command execution, output retrieval, and auditing.
The tool set covers the full read-only operational workflow: discover devices and groups, check command policy, run show commands individually or to a group, list and read saved outputs, and query the audit trail. There are no obvious dead ends—every inventory and output listing has a corresponding consumption tool.
Maintenance
Related MCP Connectors
Read-only MCP access to a documented IT fleet: state, changes, posture. 15 tools.
Read-only Linux server and Docker monitoring for AI assistants: CPU, memory, disk, network.
Let AI operate servers without SSH. Choose actions, approve risky changes, and audit every step.
Safe, read-only Postgres and MySQL access for AI agents. Audit log + column-level controls.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables AI agents to interact with Cisco IOS-XE network devices over SSH using structured tools. Provides read and write capabilities for network management with built-in validation and security.-
- AlicenseAqualityDmaintenanceBridges AI agents with network infrastructure, enabling secure read-only access to multiple vendor routers via SSH for natural language queries and troubleshooting.581MIT
- FlicenseAqualityDmaintenanceEnables LLMs to run read-only show commands on Cisco IOS/IOS-XE and Nexus switches over SSH, with a two-account model for privilege separation and a fail-closed allowlist for safety.25-
- AlicenseNot gradedqualityBmaintenanceProvides read-only, multi-vendor network device interaction, configuration auditing against vendor-guide rules, and safe diffing of proposed changes for AI agents to inspect and analyze network infrastructure without any commit or write capability.1Apache 2.0