netbox-mcp-server

Сервер Model Context Protocol, который позволяет ИИ-ассистенту читать — а если токен позволяет, и записывать — данные вашего экземпляра NetBox: DCIM, IPAM, circuits, virtualization, tenancy, power и любые плагины, установленные в этом экземпляре.

Написан на TypeScript на официальном @modelcontextprotocol/sdk. Запускается локально через stdio как подпроцесс MCP-совместимого клиента (Claude Desktop, Claude Code, Cursor, Codex).

Пять инструментов, а не несколько сотен. Типы объектов, поля, фильтры и значения перечислений не захардкожены — они вычисляются во время выполнения из собственного документа /api/schema/ подключённого экземпляра, поэтому набор инструментов описывает ваш NetBox, включая его плагины и пользовательские поля. Ответ tools/list — это около 12 000 символов описаний и схем, примерно 3000 токенов.

Устанавливаете это? Вставьте это в Claude, ChatGPT или любой ассистент, который умеет открывать ссылки и выполнять команды:

Прочитай https://raw.githubusercontent.com/zenixsolutions/netbox-mcp-server/main/AGENTS.md и следуй ему, чтобы установить NetBox MCP server на мой Mac.

AGENTS.md — это пошаговое руководство, написанное для ИИ-ассистента, чтобы тот выполнял действия без догадок. Люди могут воспользоваться «Быстрым стартом» ниже.

Быстрый старт

Клонировать и собирать ничего не нужно. Ваш MCP-клиент запускает сервер с помощью npx, который при первом использовании загружает опубликованный пакет.

Вам понадобятся:

• Node.js >= 20.11 (node --version). Node 18 достиг конца жизненного цикла и не поддерживается.

• API-токен NetBox — см. Создание токена ниже.

Claude Desktop

Отредактируйте ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) или %APPDATA%\Claude\claude_desktop_config.json (Windows). Добавьте запись netbox в уже имеющийся объект mcpServers; не заменяйте файл.

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

Используйте абсолютный путь из command -v npx как command. Claude Desktop запускается из Finder и никогда не читает ваш shell-профиль, поэтому голый "npx" — как и голый "node" — часто завершается ошибкой spawn npx ENOENT. Полностью выйдите из Claude Desktop (Cmd-Q) и откройте его заново после редактирования конфигурации.

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

Не кладите токен в ~/.zshrc или любой другой shell-профиль. Его место — в конфигурации клиента и больше нигде.

Зафиксируйте версию — "@zenixsolutions/netbox-mcp@0.2.0" — если не хотите, чтобы набор инструментов менялся между перезапусками. Версия проекта ниже 1.0.0, и CHANGELOG — это место, где фиксируются изменения набора инструментов. Для других клиентов: AGENTS.md.

Затем попросите ассистента: «Используя инструменты netbox, перечисли первые 5 площадок».

Создание токена

NetBox → ваше пользовательское меню → API Tokens → Add a token.

• Оставьте флажок Write enabled снятым, если только ассистент не должен изменять записи об инфраструктуре. Это единственный существующий контроль записи (см. Права на запись).

• Установите срок действия.

• Ограничьте объектные разрешения токена тем, что ассистенту действительно нужно.

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

Установка навыка тоже

Быстрый старт выше устанавливает инструменты. Навык netbox-modeling устанавливает суждение, которое ими управляет, — порядок создания, обязательные поля, устаревшие модели и план, который вы подтверждаете перед любой записью.

docs/installing-the-skill.md — это страница для каждой среды, с точными путями и блоками конфигурации для всех трёх мест, где запускается этот сервер:

• Claude (Desktop, Code, Cowork) — один шаг для обеих частей: /plugin marketplace add ZenixSolutions/netbox-mcp-server, затем /plugin install netbox-mcp@zenix-solutions. Плагин несёт конфигурацию сервера и навык и запрашивает URL и токен.

• ChatGPT desktop (хост Codex) — TOML в ~/.codex/config.toml, навык в ~/.agents/skills/.

• Grok Build (локальный агент xAI) — TOML в ~/.grok/config.toml, навык в ~/.grok/skills/; он также читает указанный выше плагин Claude без какой-либо настройки.

Эта страница также описывает, что обновляется само, а что нет. Если кратко: плагины Claude — да, при старте сессии; всё остальное — нет.

Пять инструментов

Предусмотренный путь для изменения: netbox_discover → netbox_describe → netbox_write. netbox_global_search — это короткий путь в обход него: поиск одного именованного объекта стоит одного вызова вместо трёх. Чтение, когда вы уже знаете тип — dcim.device, ipam.prefix — это один вызов netbox_read.

Ключи типов объектов — <app>.<model>, в единственном числе. Модели плагинов имеют вид plugins.<plugin>.<model>, и их нельзя угадать — именно для этого нужен netbox_discover.

Несколько особенностей поведения, о которых стоит знать:

• Неверный тип объекта или имя фильтра отклоняется локально — с перечислением похожих вариантов или допустимых имён фильтров. Сам NetBox отвечает 200 и возвращает всю неотфильтрованную коллекцию на нераспознанный параметр запроса, поэтому сервер отклоняет неизвестные фильтры, а не передаёт их дальше.

• netbox_write проверяет data по схеме экземпляра перед отправкой чего-либо. При отклонении возвращается то же описание, которое выдал бы netbox_describe.

• update — это частичная запись. Изменяются только поля, присутствующие в data.

• Для delete требуется, чтобы confirm совпадал с текущим значением display объекта. Сначала прочитайте объект, скопируйте display и передайте его обратно. NetBox каскадно удаляет: удаление площадки может удалить её стойки, устройства и префиксы — и это нельзя отменить.

• netbox_read и netbox_global_search по умолчанию возвращают Markdown или JSON по запросу. Списки разбиваются на страницы по 50 по умолчанию (максимум 1000) и сообщают total, has_more и next_offset; любой ответ длиннее 25 000 символов обрезается с указанием смещения, с которого можно продолжить.

Многослойность стоит дополнительных круговых обращений. Наблюдалось, что тривиальное чтение, на которое отвечает один вызов netbox_read, занимает четыре вызова, а поиск по имени — десять. Это измерено, а не оценено, и переформулировка описаний инструментов не исправила ситуацию — см. docs/reference/eval-model-in-loop.md и docs/reference/eval-results.md. Что это даёт взамен — tools/list, который помещается в окно контекста.

Обоснование архитектуры — RFC-003.

Конфигурация

Есть три переменные окружения. Других нет.

Документ OpenAPI экземпляра загружается один раз и кэшируется на диске в $XDG_CACHE_HOME/netbox-mcp (или ~/.cache/netbox-mcp) с ключом по версии NetBox и набору установленных плагинов из /api/status/. Обновление NetBox или добавление плагина делает кэш недействительным; невозможность прочитать или записать кэш никогда не является фатальной.

Права на запись

Права на запись контролируются токеном NetBox, а не этим сервером. Серверного переключателя «только чтение» нет, и это осознанное решение: переменная окружения, скрывающая инструмент записи, — это лишь рекомендация, тогда как токен со снятым write_enabled и ограниченными объектными разрешениями обеспечивается самим NetBox, куда не может дотянуться ни один аргумент инструмента.

Выдавайте токен только для чтения всем, кому не нужно изменять записи. Если запись отклонена, NetBox отвечает 403, и текст ошибки сервера называет вероятную причину — включая флаг write_enabled токена.

Подробнее о безопасной эксплуатации, включая риск промпт-инъекции при токене с правом записи: SECURITY.md.

Интерфейс командной строки

Обычно бинарный файл запускается клиентом, но у него есть четыре команды для проверки установки. Если вы собрали из клона, подставьте node dist/index.js вместо netbox-mcp.

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

# 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

Храните токен в переменной shell, а не вводите его прямо в команду: командные строки попадают в историю shell и видны в ps всем процессам на машине.

Совместимость и ограничения

Честный источник — docs/compatibility.md. Если коротко:

• Контрактно протестировано против NetBox 4.6.0 с netbox_inventory 2.6.0 — 435 проверок, 0 дефектов. Это один экземпляр, что является свидетельством, а не поддерживаемым диапазоном. Формы ответов различаются между версиями NetBox; пожалуйста, указывайте вашу версию в любом отчёте об ошибке. Документ о совместимости объясняет, как запустить набор тестов на вашем собственном экземпляре с токеном только для чтения и что прислать в ответ.

• Только stdio. Удалённого HTTP-транспорта нет, поэтому клиенты, которые говорят только по HTTP (коннекторы ChatGPT, коннекторы Grok), не могут его использовать.

• Проверен один плагин. Остальные никогда не пробовались.

• Известные ограничения — стоимость круговых обращений, имя аргумента device_id, отсутствие загрузки файлов, отсутствие GraphQL — перечислены там, а не продублированы здесь.

Сборка из клона

Для контрибьюторов и для машин, которые не могут получить доступ к 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

Выполните npm ci в оболочке, в которой NETBOX_TOKEN не экспортирован: при этом запускаются install-скрипты каждого пакета в дереве зависимостей, и каждый из них наследует ваше окружение.

Затем используйте ту же конфигурацию клиента, что и выше, указав command как абсолютный путь из command -v node, а args — как абсолютный путь к dist/index.js:

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

Тильды (~) не раскрываются MCP-клиентами — оба пути должны быть абсолютными.

Устранение неполадок

Самый частый сбой: spawn npx ENOENT / spawn node ENOENT в GUI-клиенте. Claude Desktop запускается из Finder и никогда не читает ваш ~/.zshrc, поэтому npx или node, установленные через nvm/fnm/asdf/Volta/Homebrew, ему не видны. Укажите в конфигурации абсолютный путь из command -v npx (или command -v node), а не просто строку "npx".

Второй по частоте: Missing required environment variable .... Запустите --check с теми же переменными, которые задаёт конфигурация, — команда назовёт переменную и завершится с кодом 78.

Claude Desktop ведёт логи каждого сервера отдельно:

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

Полная таблица симптомов и способов их устранения: AGENTS.md.

Разработка

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

Текст описания каждого инструмента находится рядом с его реализацией в src/tools/layered/*.ts — этот текст и есть тот интерфейс, который большинство моделей видят на самом деле, и он рецензируется соответствующим образом.

Участие в разработке

Issues и pull request'ы приветствуются — см. CONTRIBUTING.md.

Уязвимости безопасности следует сообщать приватно, а не как публичные issues. См. SECURITY.md.

Отказ от ответственности

Это независимый проект, поддерживаемый сообществом. Он не аффилирован с NetBox Labs или проектом NetBox с открытым исходным кодом, не одобрен ими и не поддерживается ими. «NetBox» — товарный знак соответствующего владельца.

Предоставляется как есть на условиях лицензии MIT. Вы несёте ответственность за то, что сделает AI-ассистент с переданными ему учётными данными, — прочтите SECURITY.md перед тем, как выпускать токен с правом записи для продакшен-инстанса NetBox.

Лицензия

MIT — см. LICENSE.