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

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

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

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

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

Ничего не записывается на устройство. Список разрешений по умолчанию запрещает всё — пустой список не разрешает ничего — и запрет всегда перевешивает разрешение.

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

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

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

Два исходных проекта от Кирка Байерса:

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

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

О 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, поэтому переменные SoT носят префикс 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 показывает 9 инструментов, /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 как источник истины, включая учётные данные

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

// .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 также берётся из SoT.

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

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 инвентаризация включает все устройства, о которых знает SoT, а это также весь набор устройств, к которым может обращаться агент. Сервер записывает предупреждение при его отсутствии; фильтр использует синтаксис запросов, tag=lab&status=active.

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

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

B — SoT для инвентаризации, учётные данные в .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 или любой SoT в форме 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 — Автономный: вообще без SoT

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

// .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) выйдет из строя, две переменные и перезапуск переводят развертывание варианта A или варианта B сюда. Это стоит отрепетировать до того, как это понадобится.

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

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

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

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.