claude-project — netmiko MCP сервер + навык

Готовый к копированию проект, который предоставляет ИИ-агенту доступ только для чтения к маршрутизаторам, коммутаторам и межсетевым экранам через SSH с использованием протокола Model Context Protocol.

Он включает две части и связку между ними:

• mcps/mcp_server_netmiko.py — самодостаточный MCP-сервер. Десять инструментов, каждая команда проверяется по заданному оператором списку разрешённых/запрещённых команд, вывод разбирается в JSON с помощью ntc-templates, а также ведётся журнал аудита всех попыток с блокировкой при отказе.

• .claude/skills/netmiko/SKILL.md — навык, который обучает агента, когда использовать эти инструменты, как выглядят диалекты CLI для разных платформ и как читать отказ.

Ничто здесь не записывает данные на устройство. Список разрешений построен по принципу «запрещено всё, что не разрешено» — пустой список не разрешает ничего, а запрет всегда имеет приоритет над разрешением.

Всё, что происходит, попадает в журнал аудита, а netmiko.query_audit_trail позволяет получать ответы в диалоге: «всё, что делалось на SW-CORE-01, по датам», «последние 6 действий», «какие команды были отклонены на этой неделе». Поскольку в этом проекте нет пользовательского интерфейса, этот инструмент — единственный способ прочитать журнал.

Авторы и происхождение

Автор этого проекта — Эд Скрималья — edgardo.scrimaglia@gmail.com, Octupus. Сервер, навык, модель конфигурации и документация — его работа, написанная для агента Niko и упакованная здесь как самостоятельный проект.

Проект начался с форка, и это происхождение признаётся, а не скрывается: отправной точкой была работа Кирка Байерса, и проект значительно её превзошёл. Всё, что здесь сейчас — инвентаризация на основе источника истины, разрешение учётных данных, три варианта развёртывания, постраничный вывод, журнал аудита, навык и эта документация — не пришло из исходного проекта.

Два вышестоящих проекта Кирка Байерса:

• Netmiko — многоплатформенная SSH-библиотека, которая непосредственно общается с устройствами.

• netmiko_mcp — MCP-сервер, от которого был сделан форк. Одна его часть сохранилась в значительной степени в исходном виде: ядро безопасности (проверка команд, обработка glob-шаблонов, асимметрия разрешений/запретов) — оно было оставлено как точный порт намеренно, чтобы патчи из вышестоящего проекта можно было по-прежнему сравнивать. Это было инженерное решение, а не ограничение для остальной работы.

Related MCP server: Network MCP Server

О Niko

Этот сервер был написан для Niko — ИИ-агента Neural Intelligence Knowledge Orchestrator, созданного Эдом Скримальей в Octupus. Niko использует набор MCP-серверов — сервер источника истины, этот, Jira, отправка писем, создание файлов и другие — чтобы оператор мог задать вопрос на естественном языке и получить ответ из реальной инфраструктуры: из источника истины — что должно быть правдой, с самих устройств — что есть на самом деле.

Внутри Niko тот же файл работает немного иначе, и это стоит знать, потому что объясняет некоторые моменты в коде:

• Серверы работают по HTTP на loopback, по одному порту каждый, объявлены в mcps/mcp_config.json с параметрами url / transport / local / env — та же двухосевая конфигурация, описанная ниже, в формате Niko.

• Установка происходит через приложение, а не копированием файлов: загрузка проверяется, зависимости разрешаются из самого кода, а неудачная установка откатывается, не оставляя половину сервера.

Каждая из этих интеграций — опциональный импорт с запасным вариантом, так что niko никогда не нужно устанавливать. Их четыре, и вот к чему сводится каждый при неудачном импорте:

Ничего важного для работы вне Niko не теряется: конкурентный обработчик решает проблему «несколько процессов — один файл», которая здесь не возникает, а бюджет списка урезает длинные полезные нагрузки для агента, у которого есть собственный учёт контекста. Один файл, два дома, без форка.

Fedele — это источник истины Niko, поэтому переменные источника истины имеют префикс FEDELE_, даже если они указывают на экземпляр NetBox.

Лицензия

Собственный код этого проекта распространяется по лицензии MIT — см. LICENSE.

Это производная работа, поэтому применяются две лицензии, и оба файла поставляются вместе:

NOTICE содержит указание авторства и заявление об изменениях, требуемое Apache-2.0 §4(b). Netmiko — обычная зависимость MIT: импортируется, не вендорится, ничего не нужно распространять.

Структура

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.toml

Два не подлежащих обсуждению правила:

1. Навык находится в .claude/skills/<имя>/SKILL.md. Claude Code не читает skills/netmiko.md: ему нужен каталог и именно такое имя файла.

2. Сервер находится в mcps/, а не в корне. PARENT_DIR — это родительский каталог каталога, содержащего .py (mcp_server_netmiko.py:62), и именно оттуда берётся .env. Если сервер находится в корне, .env будет искаться на один уровень выше проекта.

Запуск

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 server

Внутри сессии: /mcp выводит список 10 инструментов, /skills подтверждает, что навык загружен. Первая проверка, без обращения к сети:

какую политику команд применяет netmiko MCP?

Три варианта

Откуда берётся инвентаризация и откуда берутся учётные данные — это две независимые оси. Именно это даёт три варианта развёртывания на одном сервере — и причина, по которой сервер никогда не нужно модифицировать для перехода между ними: всё решают две переменные окружения.

netmiko.get_metadata сообщает, какой вариант фактически запущен — никогда не полагайтесь на конфигурационный файл:

{
  "inventory": {"backend": "fedele", "scope_filter": {"tag": "lab"}, "available": true},
  "credential_source": "env",
  "device_types_in_inventory": ["cisco_ios", "huawei_vrp", "…"]
}

A — Fedele как источник истины, включая учётные данные

Агент запрашивает устройство по имени; сервер разрешает адрес, платформу и учётные данные в источнике истины во время вызова. Никакая информация об инфраструктуре не хранится в этом проекте: добавьте устройство в источник истины, и оно станет доступно при следующем вызове без редактирования файлов и перезапуска.

// .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>

Файлы: ни один не является обязательным. commands.yml рекомендуется — без него применяется встроенная запасная политика. Локальная инвентаризация не используется, и NETMIKO_USERNAME / NETMIKO_PASSWORD не нужны; при credential_source=fedele NETMIKO_SECRET игнорируется — пароль enable также берётся из источника истины.

Как работает поиск учётных данных, три шага:

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 key

Что стоит знать, прежде чем выбирать этот вариант:

• Ключ Fernet — это вся граница безопасности. Он расшифровывает пароли устройств в памяти сервера. Относитесь к нему как к самим паролям.

• Без FEDELE_CREDENTIALS_KEY сервер всё равно запускается, но каждый инструмент возвращает одну и ту же Startup Error с указанием отсутствующей переменной. Он сообщает об ошибке громко, а не молча.

• Установите фильтр области видимости. Без NETMIKO_MCP_FEDELE_DEVICE_FILTER инвентаризация включает всю инфраструктуру, известную источнику истины, а значит, и все устройства, к которым может обратиться агент. Сервер записывает предупреждение, если фильтр отсутствует; фильтр принимает синтаксис запросов, например tag=lab&status=active.

• Устройство без primary_ip, без platform или с платформой, не являющейся device_type Netmiko, исключается из инвентаризации — источники истины также учитывают камеры, считыватели пропусков и шасси. Исключения подсчитываются и сообщаются, так что агент никогда не заявит «это все устройства» на основе подмножества.

• Есть автоматический выключатель: после транспортной ошибки или 5xx клиент прекращает обращаться к источнику истины на 30 с. Групповая команда для 40 устройств при недоступном источнике истины завершится ошибкой один раз, а не сорок.

B — Источник истины для инвентаризации, учётные данные в .env

Идентично варианту A с одной изменённой переменной:

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

Вы получаете динамическую инвентаризацию — ту часть, которая окупает себя — без плагина учётных данных и без ключа Fernet. Для всех устройств используется одна учётная запись службы.

NetBox или любой источник истины в форме NetBox

Бэкенд инвентаризации использует диалект REST NetBox, поэтому сам NetBox работает в этом варианте без изменений:

Укажите FEDELE_URL на экземпляр NetBox (/api добавляется, если вы его опустите) и FEDELE_TOKEN на API-токен NetBox — клиент аутентифицируется с заголовком Authorization: Token …, который ожидает NetBox. Переменные сохраняют префикс FEDELE_; это наследие именования, а не требование продукта.

Единственное требование, которое NetBox не удовлетворяет по умолчанию: platform.name должен быть в точности device_type Netmiko — cisco_ios, arista_eos, huawei_vrp, juniper_junos. Платформа с именем «Cisco IOS 15.2» не является device_type, поэтому все устройства с ней исключаются из инвентаризации. Либо переименуйте платформы в NetBox, либо примите исключения, о которых сообщается.

Учётные данные — это та часть, которую NetBox не покрывает: конечные точки plugins/credentials/… принадлежат плагину Fedele. С обычным NetBox вариант A недоступен — оставайтесь на B.

C — Автономный: вообще без источника истины

Всё находится в этом проекте. Никакой внешний сервис никогда не вызывается.

// .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>

Файлы: inventory.yml обязателен здесь — это единственное место, где существуют устройства. commands.yml остается рекомендованным, но не обязательным. Инвентарь использует формат netmiko_tools — плоское сопоставление имени с данными подключения, а также ключи групп:

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

Файл, поставляемый с этим проектом, содержит пример данных: 12 вымышленных устройств на диапазонах документации RFC 5737, 7 групп и платформы, подобранные так, чтобы были представлены все диалекты CLI, упомянутые в списке разрешений. Замените его на свои собственные данные.

Это конфигурация, с которой поставляется этот проект, и это также режим пониженной функциональности: если система истины (SoT) выходит из строя, две переменные и перезапуск переводят развертывание flavor-A или flavor-B в этот режим. Стоит отрепетировать это до того, как понадобится.

Плата за это — файл устаревает. scripts/export_inventory.py в родительском репозитории регенерирует его из SoT; запускайте его по расписанию. Резервный инвентарь с адресами полугодовой давности хуже, чем полное отсутствие резервной копии, потому что вы узнаете об этом во время работы.

Что остается неизменным во всех трех вариантах

Политика команд, журнал аудита, разбивка вывода на страницы и поверхность инструментов не меняются между вариантами. Контракт, видимый агенту, идентичен, поэтому навыку не нужен вариант для каждого flavor.

commands.yml рекомендован, но не обязателен

Сервер работает и без него. Если файл отсутствует, он не блокирует все команды и не отказывается запускаться: встроенный запасной вариант из 16 команд только для чтения вступает в силу — show version, show ip interface brief, display version и их эквиваленты для Junos/VRP. Это сделано намеренно. Пустая политика блокировала бы каждую команду, в то время как сервер сообщал бы о своем исправном состоянии, что оператор воспринял бы как «устройство отказало», а не «никто не написал политику». Запасной вариант объявляется при запуске, netmiko.get_command_policy сообщает policy_source: "fallback", и каждая аудируемая попытка содержит источник.

Таким образом, файл — это политическое решение, а не шаг установки: запасной вариант позволяет запустить сервер с первой попытки, а commands.yml вы пишете, когда хотите использовать собственную политику вместо консервативной по умолчанию. Чего вы не можете сделать, так это иметь политику, которую вы не выбирали, и не знать об этом — сервер сообщает, какая из них действует, каждый раз, когда его спрашивают.

Файл .mcp.json

.mcp.json в корне проекта объявляет MCP-серверы для этого проекта. Claude Code запрашивает подтверждение при первом обнаружении файла, и файл предназначен для фиксации в репозитории: так вся команда получает один и тот же сервер.

Существуют две другие области видимости для того же определения сервера:

claude mcp add --scope project netmiko -- /path/to/python /path/to/server.py записывает запись project за вас; редактирование JSON вручную эквивалентно.

Структура файла

{
  "mcpServers": {           // ← the top-level key. Not "servers", not "mcp".
    "netmiko": {            // ← the server name; it becomes the tool prefix
      ...                   //    mcp__netmiko__<tool>
    }
  }
}

Имя сервера не просто косметическое: Claude Code предоставляет каждый инструмент как mcp__<server-name>__<tool-name>. С именем netmiko и инструментом netmiko.get_metadata, который регистрирует сервер, инструмент, который видит Claude, на самом деле называется mcp__netmiko__netmiko.get_metadata. Запустите /mcp, чтобы прочитать точные имена перед тем, как вписать их в список allowed-tools или правило разрешений.

Справочник полей

Значения поддерживают подстановку переменных окружения: ${VAR} и ${VAR:-default}. Полезно для хранения токена вне зафиксированного файла:

"headers": { "Authorization": "Bearer ${NETMIKO_MCP_TOKEN}" }

Транспорт 1 — stdio (используется в этом проекте)

Claude Code запускает сервер как дочерний процесс и общается с ним через JSON-RPC по его stdin/stdout. Ничто не слушает порт, ничто не доступно из сети, и время жизни процесса равно времени сессии. Это правильный выбор по умолчанию для сервера, хранящего 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"
      }
    }
  }
}

Две вещи, которые могут укусить:

• Никаких жестко заданных путей, и на рабочую директорию полагаться не стоит. ${CLAUDE_PROJECT_DIR:-.} — это то, что позволяет фиксировать файл как есть; следующий раздел рассказывает всю историю, потому что очевидное прочтение этого неверно.

• Сервер не должен писать в stdout. stdout является каналом протокола, и одна случайная строка там нарушает сессию. Логирование идет в stderr плюс в ротируемый файл по пути LOG_FILE (5 МБ × 3, создается с правами 0600 — на уровне DEBUG этот файл содержит вывод устройств). Внутри Niko та же переменная обрабатывается MCPLogging.

Откуда берется ${CLAUDE_PROJECT_DIR:-.}

Две разные вещи в одной строке: синтаксис и переменная.

Синтаксис. ${VAR} и ${VAR:-default} — это подстановка параметров POSIX («используй VAR; если он не установлен или пуст, используй default»), но здесь не задействована оболочка — JSON-файл никогда через нее не проходит. Claude Code сам реализует подстановку при чтении файла, в полях command, args, env, url и headers. Это соглашение именно этого клиента, а не часть спецификации MCP: другой клиент может его не реализовывать (см. Не-Claude агенты, где пути тогда должны быть литеральными), а у VS Code есть свое написание, ${workspaceFolder}.

Переменная. CLAUDE_PROJECT_DIR устанавливается Claude Code в корень проекта, то же значение, которое получают хуки. Она стабильна — предоставление дополнительных рабочих директорий во время сессии с помощью --add-dir не меняет ее.

Контринтуитивная часть, и причина, по которой :-. не просто украшение: Claude Code устанавливает эту переменную в окружении запускаемого сервера, а не в своем собственном. Однако подстановка происходит до запуска, в окружении Claude Code — где переменная не существует. Голый ${CLAUDE_PROJECT_DIR} поэтому развернулся бы в ничто и оставил /config/netmiko/inventory.yml, абсолютный путь к корню файловой системы.

Таким образом, в .mcp.json с областью видимости project значение по умолчанию — это не запасной вариант для какого-то крайнего случая: это значение, которое используется всегда. До процесса доходит ./config/netmiko/inventory.yml. Единственное исключение — конфигурация MCP, поставляемая плагином — там Claude Code подставляет переменную напрямую, и значение по умолчанию не нужно.

Именно это и связывает серверу руки. Относительное значение разрешалось бы относительно cwd дочернего процесса, а cwd — это выбор клиента, а не проекта. Отсюда resolve_project_path(): каждый относительный путь в настройках привязывается к PARENT_DIR — родительской директории mcps/, тому же корню, откуда берется .env — при загрузке настроек. Сессия, запущенная откуда угодно, находит config/netmiko/, а validate_startup() называет абсолютный файл, когда он отсутствует. ~ по-прежнему означает домашнюю директорию оператора, а не файл внутри проекта.

Переменная все еще полезна так, как задумано в документации, при чтении изнутри сервера (os.environ["CLAUDE_PROJECT_DIR"]), где она установлена. Этому серверу она не нужна: PARENT_DIR выводится из __file__ и, следовательно, не зависит ни от какого клиента — по той же причине HTTP-транспорт, где никто не устанавливает эту переменную, не требует особого обращения.

Источник: Claude Code — MCP, разделы Add a local stdio server и Environment variable expansion in .mcp.json.

Транспорт 2 — HTTP (потоковый HTTP)

Claude Code его поддерживает, как и любой другой MCP-клиент. Это транспорт, который следует использовать, когда сервер работает где-то еще: на другом хосте, в контейнере, в сервисе, используемом несколькими агентами, или агентом, отличным от Claude.

Файл сервера всегда вызывает mcp.run(transport="stdio") под своей защитой __main__, поэтому HTTP обслуживается через CLI FastMCP — без изменения кода:

.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/

Переменные NETMIKO_MCP_* больше не являются частью конфигурации клиента: серверный процесс запускается вами, поэтому они принадлежат его окружению (экспорт в оболочке, unit systemd, блок environment: контейнера).

Сторона клиента:

{
  "mcpServers": {
    "netmiko": {
      "type": "http",
      "url": "http://127.0.0.1:8123/mcp/",
      "headers": {
        "Authorization": "Bearer ${NETMIKO_MCP_TOKEN}"
      }
    }
  }
}

Или, что эквивалентно, claude mcp add --transport http netmiko http://127.0.0.1:8123/mcp/.

--transport sse и "type": "sse" также работают; SSE — это более старый удаленный транспорт, который сохраняется для клиентов, еще не перешедших на потоковый HTTP.

Безопасность. CLI FastMCP обслуживает это без какой-либо аутентификации: любой, кто имеет доступ к порту, может выполнять команды show на всех устройствах в инвентаре, используя учетные данные из окружения сервера. Привязывайтесь к 127.0.0.1 для локального тестирования, а для чего-либо общего используйте обратный прокси-сервер, который завершает TLS и проверяет заголовок Authorization. Блок headers выше — это то, что отправляет клиент; прокси-сервер — это то, что должно это проверять.

Не-Claude агенты

Объект mcpServers, показанный здесь, является фактическим стандартом: Claude Code, Claude Desktop, Cursor и Windsurf все читают одни и те же три поля для stdio (command / args / env) и те же два для удаленного доступа (url / headers). Копирование записи между ними обычно работает как есть.

Известные различия, которые стоит проверить перед копированием:

• VS Code использует mcp.json с ключом верхнего уровня "servers" вместо "mcpServers" и требует явного указания "type".

• Некоторые клиенты не реализуют подстановку ${VAR}; там значение должно быть литеральным, что является аргументом в пользу HTTP-транспорта с прокси, а не токена, вставленного в зафиксированный файл.

• Агент без какого-либо конфигурационного файла все равно может напрямую общаться с HTTP-конечной точкой — URL и заголовок Authorization составляют весь контракт.

Блок env

Записи NETMIKO_MCP_* имеют приоритет над любым YAML-конфигурационным файлом. Они установлены явно, потому что вне Niko нет NikoPaths, поэтому значения по умолчанию возвращаются к ~/commands.yml и ~/.netmiko_mcp_tmp.

Каждый путь здесь может быть указан относительно корня проекта: сервер привязывает относительные значения к PARENT_DIR при загрузке настроек, поэтому cwd запущенного процесса никогда не определяет, где находится инвентарь или журнал аудита. Абсолютный путь или ~ используются как есть.

Учётные данные не задаются здесь. NETMIKO_USERNAME, NETMIKO_PASSWORD, NETMIKO_SECRET и переменные FEDELE_* читаются из <project-root>/.env, чтобы они никогда не оказались в зафиксированном JSON-файле. Приоритет: то, что находится в блоке env, переопределяет .env без предупреждения — определяйте каждую переменную ровно в одном месте.

Все остальные переменные описаны в README родительского репозитория.

Проверка работоспособности

claude mcp list          # netmiko: ✓ connected

Внутри сессии /mcp выводит список инструментов, а /skills подтверждает, что навык загружен. Спросите, какая политика действует, и netmiko.get_command_policy укажет имя файла, который он читает — или сообщит "fallback", что означает, что файл не найден и используются 16 встроенных команд.

Автор: Ed Scrimaglia edgardo.scrimaglia@gmail.com — последнее обновление: 2026-08-18.