netbox-mcp-server

AI 어시스턴트가 NetBox 인스턴스의 DCIM, IPAM, circuits, virtualization, tenancy, power 및 해당 인스턴스에 설치된 플러그인을 읽고 — 토큰이 허용하면 쓰고 — 할 수 있게 해주는 Model Context Protocol 서버입니다.

공식 @modelcontextprotocol/sdk 기반의 TypeScript로 작성되었습니다. MCP를 인식하는 클라이언트(Claude Desktop, Claude Code, Cursor, Codex)의 하위 프로세스로 stdio를 통해 로컬에서 실행됩니다.

다섯 개의 도구이지 수백 개가 아닙니다. 객체 유형, 필드, 필터, 열거형 값은 하드코딩되어 있지 않습니다. 연결된 인스턴스 자체의 /api/schema/ 문서에서 런타임에 파생되므로, 제공되는 표면은 당신의 NetBox — 플러그인과 사용자 정의 필드를 포함해 — 를 설명합니다. tools/list 응답은 설명과 스키마로 약 12,000자, 대략 3,000 토큰입니다.

설치하시겠어요? 이 내용을 Claude, ChatGPT, 또는 웹을 탐색하고 명령을 실행할 수 있는 어시스턴트에 붙여넣으세요:

https://raw.githubusercontent.com/zenixsolutions/netbox-mcp-server/main/AGENTS.md 를 읽고 그 내용에 따라 내 Mac에 NetBox MCP 서버를 설치해 주세요.

AGENTS.md는 AI 어시스턴트가 추측 없이 실행할 수 있도록 단계별로 작성된 런북입니다. 사람은 아래 Quick start를 사용해도 됩니다.

빠른 시작

클론하거나 빌드할 것이 없습니다. MCP 클라이언트는 npx로 서버를 실행하며, 첫 사용 시 게시된 패키지를 가져옵니다.

필요한 것:

• Node.js >= 20.11 (node --version). Node 18은 수명 종료(EOL)이므로 지원되지 않습니다.

• NetBox API 토큰 — 아래 토큰 생성을 참조하세요.

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json(macOS) 또는 %APPDATA%\Claude\claude_desktop_config.json(Windows)을 편집하세요. 기존에 있는 mcpServers 객체에 netbox 항목을 추가하세요. 파일을 교체하지 마세요.

{
  "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에는 command -v npx의 절대 경로를 사용하세요. Claude Desktop은 Finder에서 실행되며 셸 프로필을 절대 읽어들이지 않으므로, "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나 다른 셸 프로필에 넣지 마세요. 토큰은 클라이언트 설정에만 있어야 하며 다른 곳에는 없어야 합니다.

재시작 사이에 도구 표면이 바뀌는 것을 원하지 않으면 버전을 고정하세요 — "@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

스킬도 함께 설치하기

위의 빠른 시작은 도구만 설치합니다. 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자를 초과하는 응답은 이어서 계속할 offset과 함께 잘립니다.

레이어링은 왕복 비용을 발생시킵니다. 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) 아래 디스크에 캐시되며, /api/status/의 NetBox 버전과 설치된 플러그인 세트를 키로 사용합니다. NetBox를 업그레이드하거나 플러그인을 추가하면 캐시는 무효화됩니다. 읽거나 쓸 수 없는 캐시는 결코 치명적이지 않습니다.

쓰기 액세스

쓰기 액세스는 이 서버가 아니라 NetBox 토큰으로 제어됩니다. 서버 측 읽기 전용 스위치는 없으며, 이는 의도적입니다. 쓰기 도구를 숨기는 환경 변수는 제안일 뿐이지만, write_enabled가 체크되어 있지 않고 객체 권한이 범위 제한된 토큰은 NetBox가 강제하며, 도구 인자로는 거기에 닿을 수 없습니다.

레코드를 변경할 필요가 없는 사람에게는 읽기 전용 토큰을 발급하세요. 쓰기가 거부되면 NetBox는 403으로 응답하고 서버의 오류 텍스트는 토큰의 write_enabled 플래그를 포함해 가능한 원인을 언급합니다.

쓰기가 가능한 토큰의 프롬프트 인젝션 위험을 포함한 안전한 운영에 대한 자세한 내용은 SECURITY.md를 참조하세요.

명령줄 인터페이스

바이너리는 보통 클라이언트가 실행하지만, 설치를 확인하기 위한 네 가지 동사가 있습니다. 클론에서 빌드했다면 netbox-mcp 대신 node dist/index.js를 사용하세요.

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

토큰을 명령에 직접 입력하지 말고 셸 변수에 보관하세요. 명령줄은 셸 히스토리에 남고 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

NETBOX_TOKEN이 내보내지지 않은 셸에서 npm ci를 실행하세요. 이 명령은 의존성 트리의 모든 패키지의 설치 스크립트를 실행하며, 각 스크립트는 사용자의 환경을 상속받습니다.

그런 다음 위와 동일한 클라이언트 설정을 사용하되, 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 클라이언트에서 확장되지 않으므로 두 경로 모두 절대 경로여야 합니다.

문제 해결

단연 가장 흔한 실패는 GUI 클라이언트에서 spawn npx ENOENT / spawn node ENOENT 오류입니다. Claude Desktop은 Finder에서 실행되며 ~/.zshrc를 불러오지 않으므로 nvm/fnm/asdf/Volta/Homebrew로 설치된 npx 또는 node를 인식하지 못합니다. 설정에 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의 구현 옆에 있습니다. 이 텍스트는 대부분의 모델이 실제로 보는 인터페이스이며, 그에 맞게 검토됩니다.

기여

이슈와 풀 리퀘스트를 환영합니다 — CONTRIBUTING.md를 참조하세요.

보안 취약점은 공개 이슈가 아닌 비공개로 보고해야 합니다. SECURITY.md를 참조하세요.

면책 조항

이 프로젝트는 독립적이고 커뮤니티가 유지 관리하는 프로젝트입니다. NetBox Labs 또는 NetBox 오픈소스 프로젝트와는 제휴, 보증, 지원 관계가 아닙니다. "NetBox"는 해당 소유주의 상표입니다.

MIT 라이선스에 따라 있는 그대로 제공됩니다. AI 어시스턴트가 사용자가 제공한 자격 증명으로 수행하는 작업에 대한 책임은 사용자에게 있습니다. 프로덕션 NetBox 인스턴스에 쓰기 권한이 있는 토큰을 발급하기 전에 SECURITY.md를 읽으세요.

라이선스

MIT — LICENSE를 참조하세요.