netbox-mcp-server

Model Context Protocol サーバーで、AI アシスタントが NetBox インスタンスを読み取り（トークンが許可すれば書き込みも）できるようにするものです。対象は DCIM、IPAM、回線、仮想化、テナント、電源、そしてそのインスタンスにインストールされているプラグインすべてです。

公式の @modelcontextprotocol/sdk 上で TypeScript で書かれています。MCP 対応クライアント（Claude Desktop、Claude Code、Cursor、Codex）のサブプロセスとして、stdio 経由でローカルに実行されます。

5つのツール。何百ものツールではありません。 オブジェクトタイプ、フィールド、フィルター、enum 値はハードコードされておらず、接続先インスタンス自身の /api/schema/ ドキュメントから実行時に導出されます。そのため、そのサーフェスは、プラグインやカスタムフィールドを含む あなたの NetBox を記述します。tools/list のレスポンスは、説明とスキーマで約 12,000 文字、およそ 3,000 トークンです。

これをインストールしますか? これを Claude、ChatGPT、またはブラウズやコマンド実行ができるアシスタントに貼り付けてください:

https://raw.githubusercontent.com/zenixsolutions/netbox-mcp-server/main/AGENTS.md を読んで、それに従って NetBox MCP サーバーを私の Mac にインストールしてください。

AGENTS.md は、AI アシスタントが推測せずに実行できるように書かれたステップバイステップの手順書です。人間は代わりに下の「クイックスタート」を使用できます。

クイックスタート

クローンやビルドは不要です。MCP クライアントが npx でサーバーを起動し、初回使用時に公開パッケージを取得します。

必要なもの:

• Node.js >= 20.11 (node --version)。Node 18 はサポート終了 (end-of-life) であり、サポートされていません。

• 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 -v npx の 絶対パス を command に使用してください。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 トークン → トークンを追加。

• アシスタントがインフラストラクチャのレコードを変更することを意図していない限り、Write enabled はオフのままにしてください。これが唯一の書き込み制御です（書き込みアクセス を参照）。

• 有効期限を設定します。

• トークンのオブジェクト権限を、アシスタントが実際に必要とする範囲に制限します。

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

スキルもインストールする

上記のクイックスタートではツールをインストールします。netbox-modeling スキルは、それらを動かす判断基準を取り込みます — 構築順序、必須フィールド、非推奨モデル、そして何かを書き込む前に確認する計画です。

docs/installing-the-skill.md は、このサーバーが実行される 3 つの場所すべてについて、正確なパスと設定ブロックを示す、各サーフェス向けのページです。

• Claude（Desktop、Code、Cowork）— 両方の部分を 1 ステップで行います: /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 プラグインはセッション開始時に更新されますが、それ以外は更新されません。

5つのツール

変更を行う際の意図された経路は、netbox_discover → netbox_describe → netbox_write です。netbox_global_search はその近道です。名前付きオブジェクトを 1 つ調べるのに 3 回ではなく 1 回の呼び出しで済みます。型がすでにわかっている読み取り — dcim.device、ipam.prefix — は netbox_read への 1 回の呼び出しです。

オブジェクトタイプのキーは <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 文字を超えるレスポンスは、再開するためのオフセット付きで切り詰められます。

レイヤリングにはラウンドトリップのコストがかかります。 1 回の netbox_read 呼び出しで答えられる単純な読み取りが、4 回の呼び出しを要した例が観測されており、名前の検索では 10 回です。これは推測ではなく測定です。ツールの説明を言い換えても修正されませんでした — docs/reference/eval-model-in-loop.md と docs/reference/eval-results.md を参照してください。その代わりに得られるのは、コンテキストウィンドウに収まる tools/list です。

設計の根拠は RFC-003 です。

設定

環境変数は 3 つです。他にはありません。

インスタンスの OpenAPI ドキュメントは一度取得され、$XDG_CACHE_HOME/netbox-mcp（または ~/.cache/netbox-mcp）のディスク上にキャッシュされます。キーは /api/status/ から取得した NetBox バージョンとインストール済みプラグインセットです。NetBox のアップグレードまたはプラグインの追加でキャッシュは無効化されます。読み取りまたは書き込みができないキャッシュがあっても、致命的になることはありません。

書き込みアクセス

書き込みアクセスはこのサーバーではなく、NetBox トークンによって制御されます。 サーバー側の読み取り専用スイッチはありません。これは意図的です。書き込みツールを隠す環境変数は提案にすぎませんが、write_enabled がオフでオブジェクト権限が制限されたトークンは NetBox によって強制され、ツールの引数ではそこに到達できません。

レコードを変更する必要がない人には、読み取り専用トークンを発行してください。書き込みが拒否された場合、NetBox は 403 を返し、サーバーのエラーテキストは考えられる原因を挙げます — トークンの write_enabled フラグを含みます。

書き込み可能なトークンでのプロンプトインジェクションのリスクを含む、これを安全に運用するための詳細は SECURITY.md を参照してください。

コマンドラインインターフェース

バイナリは通常クライアントから起動されますが、インストールを検証するための 4 つの動詞があります。クローンからビルドした場合は、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 欠陥。 これは 1 つのインスタンスであり、根拠にはなりますが、サポート範囲ではありません。レスポンスの形は NetBox のバージョンによって異なります。バグ報告にはあなたのバージョンを含めてください。互換性ドキュメントには、読み取り専用トークンを使って自分のインスタンスに対してスイートを実行する方法と、何を返送するかが説明されています。

• stdio のみ。 リモート HTTP トランスポートはないため、HTTP のみを話すクライアント（ChatGPT コネクタ、Grok コネクタ）はこれを使用できません。

• 1 つのプラグインが検証済みです。他のプラグインは試されたことがありません。

• 既知の制限事項 — ラウンドトリップコスト、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" は指定しないでください。

2番目に多いのは、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 内の実装の隣にあります — このテキストは、ほとんどのモデルが実際に目にするインターフェースであり、そのようにレビューされます。

貢献

Issueとプルリクエストを歓迎します — CONTRIBUTING.md を参照してください。

セキュリティの脆弱性は、公開Issueとしてではなく、非公開で報告してください。SECURITY.md を参照してください。

免責事項

これは独立した、コミュニティによって保守されているプロジェクトです。NetBox LabsやNetBoxオープンソースプロジェクトとは提携関係がなく、その承認や支援も受けていません。"NetBox" はそれぞれの所有者の商標です。

MITライセンスの下で現状のまま提供されます。あなたがAIアシスタントに与えた認証情報を、そのAIアシスタントがどのように使用するかについては、あなたに責任があります。本番のNetBoxインスタンス用に書き込み可能なトークンを発行する前に、SECURITY.md を読んでください。

ライセンス

MIT — LICENSE を参照してください。