NetBox MCP

NetBox MCP サーバーは、ネットワークインフラストラクチャ（DCIM および IPAM）の信頼できる情報源である NetBox への構造化されたアクセスを AI アシスタントに提供する、Python ベースの Model Context Protocol（MCP）サーバーです。汎用ツールの小さなセットで、NetBox 4.7 の 139 種類すべてのコアオブジェクトタイプ（有効な場合はプラグインのタイプも）に対応し、さらに検索、変更ログ、GraphQL、空き IP／プレフィックス／VLAN の割り当て、ケーブルのトレース、設定のレンダリング、（オプションの）netbox-branching 用の専用ツールも備えています。書き込みを完全に非表示にする（読み取り専用モード）ことも、シミュレーションする（ドライランモード）こともできます。

✨ 機能

コア機能

• 1 つのツールで、フィルタリング、並べ替え、ページネーションを使ってあらゆる NetBox オブジェクトタイプを検索できます
• fields、omit、brief を使ってレスポンスを小さく保てます。ツールはモデルにこれらを使うよう促します
• 複数のオブジェクトタイプを一度に検索し、失敗したタイプや結果が切り詰められたタイプを明示的に報告します
• 変更ログ（誰が、いつ、何を変更したか）と、NetBox のステータス／バージョン／プラグインを読み取れます
• 読み取り専用の GraphQL クエリを実行し、1 回のラウンドトリップでネストされたデータを取得できます
• 空き IP、プレフィックス、VLAN、ASN の一覧表示、ケーブル経路のトレース、デバイス設定のレンダリングができます

管理操作

• 単一または一括で、あらゆるオブジェクトタイプを作成、更新、削除できます（NetBox は一括書き込みを 1 つのトランザクションとして実行します）
• 次の空き IP、プレフィックス、VLAN、ASN をアトミックに割り当てます
• オプションで、main ではなく netbox-branching のブランチに変更を反映できます
• 書き込み前に、オブジェクトタイプの書き込み可能なフィールドと選択肢を確認できます

高度な機能

• 読み取り専用モードではすべての書き込みツールが非表示になり、ドライランモードではすべての書き込みがプレビューになります
• NetBox v2（Bearer nbt_...）および従来の v1（Token ...）API トークン
• プラグインのオブジェクトタイプ検出（例：netbox_dns.zone）
• NetBox が黙って無視するフィルター（__in、複数ホップのルックアップ）を拒否するフィルター検証
• 429／5xx の場合は再試行しますが、サーバーエラー後に作成リクエストを再実行することはありません
• タグベースのツールフィルタリング、オプションのツール検索トランスフォーム、レート制限、レスポンスサイズ制限
• HTTP トランスポートでの Bearer トークン認証
• 複数のトランスポートオプション（STDIO、SSE、HTTP）
• エラー追跡用のオプションの Sentry 統合

🚀 インストール

前提条件

• Python 3.11～3.15
• バージョン 4.2 以降の NetBox インスタンス。後から追加された機能（omit、v2 トークン、/api/authentication-check/）は、サーバーが対応を検出した場合に使用されます
• アシスタントに許可する権限を持つ NetBox API トークン。この トークンが実際のセキュリティ境界です。このサーバーの設定にかかわらず、 読み取り専用トークンでは書き込みできません

PyPI からのクイックインストール

最も簡単に始めるには、PyPI からインストールしてください。

# Using UV (recommended)
uvx netbox-mcp

# Or using pip
pip install netbox-mcp

サーバーを実行する前に、NetBox インスタンスの環境変数を設定してください。

# Create environment configuration
export NETBOX_URL=https://netbox.example.com
export NETBOX_TOKEN=nbt_your-key.your-token

ソースからのインストール

1. リポジトリをクローンします。

git clone https://github.com/mhajder/netbox-mcp.git
cd netbox-mcp

2. 依存関係をインストールします。

# Using UV (recommended)
uv sync

# Or using pip
pip install -e .

3. 環境変数を設定します。

cp .env.example .env
# Edit .env with your NetBox URL and API token

4. サーバーを実行します。

# Using UV (recommended)
uv run netbox-mcp

# Or using the installed command directly
netbox-mcp

Docker の使用

簡単にデプロイできるよう、Docker イメージが GitHub Packages で公開されています。

docker pull ghcr.io/mhajder/netbox-mcp:latest

開発環境のセットアップ

追加ツールを使った開発を行う場合：

# Clone and install with development dependencies
git clone https://github.com/mhajder/netbox-mcp.git
cd netbox-mcp
uv sync --group dev

# Run tests
uv run pytest

# Run with coverage
uv run pytest --cov=src/

# Run linting and formatting
uv run ruff check .
uv run ruff format .

# Run type checking
uv run ty check .

# Setup prek hooks
uv run prek install

🔧 設定

環境変数

# NetBox MCP Server Environment Configuration

# NetBox Connection Details
NETBOX_URL=https://netbox.example.com

# API Token - v2 tokens (nbt_<key>.<token>, NetBox 4.5+) are sent as "Bearer",
# legacy v1 tokens as "Token"
NETBOX_TOKEN=nbt_your-key.your-token

# SSL Configuration
NETBOX_VERIFY_SSL=true
# Total time allowed for one NetBox request, retries included (seconds)
NETBOX_TIMEOUT=30

# Branching (requires the netbox-branching plugin)
# Set NETBOX_BRANCHING_ENABLED true to add the branch tools and the 'branch'
# argument to every tool. Off by default - leave it off on a NetBox without the plugin
NETBOX_BRANCHING_ENABLED=false
# Default branch (name or schema ID) used by every call; empty = main.
# Requires NETBOX_BRANCHING_ENABLED=true
NETBOX_BRANCH=

# Plugin Discovery
# Set NETBOX_PLUGIN_DISCOVERY true to expose plugin models (e.g. netbox_dns.zone)
NETBOX_PLUGIN_DISCOVERY=false

# Read-Only Mode
# Set READ_ONLY_MODE true to hide all write tools (create, update, delete)
READ_ONLY_MODE=false

# Dry-Run Mode
# Set DRY_RUN_MODE true to make every write tool only simulate the change:
# it returns the request it would send and never modifies NetBox
DRY_RUN_MODE=false

# Disabled Tags
# Comma-separated list of tags to disable tools for (empty by default)
# Example: DISABLED_TAGS=delete,graphql,branching
DISABLED_TAGS=

# Logging Configuration
LOG_LEVEL=INFO

# Response Size Limit
# Maximum tool response size in bytes; larger responses are truncated (empty = unlimited)
RESPONSE_MAX_SIZE=

# Rate Limiting
# Set RATE_LIMIT_ENABLED true to enable rate limiting
RATE_LIMIT_ENABLED=false
RATE_LIMIT_MAX_REQUESTS=60
RATE_LIMIT_WINDOW_MINUTES=1

# Tool Search Transform (Optional)
# Set TOOL_SEARCH_ENABLED true to replace full tool listings with search_tools + call_tool
TOOL_SEARCH_ENABLED=false
# Search strategy: bm25 (natural language) or regex (pattern match)
TOOL_SEARCH_STRATEGY=bm25
# Maximum number of tools returned by search_tools
TOOL_SEARCH_MAX_RESULTS=5

# Sentry Error Tracking (Optional)
# Set SENTRY_DSN to enable error tracking and performance monitoring
# SENTRY_DSN=https://[email protected]/6789
# Optional Sentry configuration
# SENTRY_TRACES_SAMPLE_RATE=1.0
# SENTRY_SEND_DEFAULT_PII=false
# SENTRY_ENVIRONMENT=production
# SENTRY_RELEASE=1.2.3
# SENTRY_PROFILE_SESSION_SAMPLE_RATE=1.0
# SENTRY_PROFILE_LIFECYCLE=trace
# SENTRY_ENABLE_LOGS=true

# MCP Transport Configuration
# Transport type: 'stdio' (default), 'sse' (Server-Sent Events), or 'http' (HTTP Streamable)
# 'streamable-http' is accepted as an alias for 'http'. Any other value stops
# the server at startup.
# MCP_TRANSPORT=stdio

# HTTP Transport Settings (used when MCP_TRANSPORT=sse or MCP_TRANSPORT=http)
# Host to bind the HTTP server (default: 127.0.0.1)
# MCP_HTTP_HOST=127.0.0.1
# Port to bind the HTTP server (default: 8000)
# MCP_HTTP_PORT=8000
# Optional bearer token for authentication (leave empty for no auth)
# MCP_HTTP_BEARER_TOKEN=
# Set NETBOX_TOKEN_PASSTHROUGH true to make every client authenticate with its own
# NetBox API token (Authorization: Bearer <token>); NetBox then applies that user's
# permissions. NETBOX_TOKEN is ignored. Cannot be combined with MCP_HTTP_BEARER_TOKEN
# NETBOX_TOKEN_PASSTHROUGH=false

🧰 利用可能なツール

オブジェクトタイプは、NetBox 自体の命名規則に従って app.model 形式で指定します（dcim.device、ipam.prefix、virtualization.virtualmachine）。dcim/devices などの API パスも使用できます。ブランチ機能が有効な場合、オブジェクトを読み取る、または書き込むすべてのツールで、オプションの branch 引数も使用できます。

オブジェクト（読み取り）

ツール	説明
netbox_list_object_types	サポート対象のオブジェクトタイプとエンドポイントを一覧表示します（コアおよび検出されたプラグインタイプ）
netbox_get_objects	filters、fields、omit、brief、ordering、limit、offset を指定して、あるタイプのオブジェクトを一覧表示します
netbox_get_object	ID を指定して 1 つのオブジェクトを取得します
netbox_search_objects	複数のオブジェクトタイプを一度に対象として、フリーテキスト検索（q）を行います
netbox_describe_object_type	あるタイプの書き込み可能なフィールドを表示します：データ型、必須項目、選択肢
netbox_get_changelogs	変更ログのエントリーを新しい順に表示します

特化型（読み取り）

ツール	説明
netbox_get_status	NetBox のバージョン、プラグイン、ワーカー、認証済みユーザー、およびこのサーバーのモードを表示します
netbox_graphql_query	読み取り専用の GraphQL クエリを実行します（ミューテーションは拒否されます）
netbox_get_available	プレフィックスまたは IP 範囲内の空き IP／プレフィックス、VLAN グループ内の VLAN、ASN 範囲内の ASN を表示します
netbox_trace_cable	インターフェイス、前面／背面／コンソール／電源ポート、または回線終端から、ケーブル経路全体を表示します
netbox_render_config	デバイスまたは VM の設定を、その設定テンプレートからレンダリングします
netbox_list_branches	netbox-branching のブランチを一覧表示します（NETBOX_BRANCHING_ENABLED=true の場合のみ）

書き込み

ツール	説明
netbox_create_object	1 つのオブジェクトを作成します
netbox_update_object	1 つのオブジェクトを部分更新します（PATCH）
netbox_bulk_create_objects	1 回のトランザクションで最大 500 個のオブジェクトを作成します
netbox_bulk_update_objects	1 回のトランザクションで最大 500 個のオブジェクトを更新します
netbox_allocate_available	次に利用可能な IP、プレフィックス、VLAN、または ASN を割り当てます
netbox_create_branch	netbox-branching のブランチを作成します（NETBOX_BRANCHING_ENABLED=true の場合のみ）
netbox_delete_object	1 つのオブジェクトを削除します（destructiveHint）
netbox_bulk_delete_objects	1 回のトランザクションで最大 500 個のオブジェクトを削除します（destructiveHint）

ツールタグ

各ツールには netbox とグループタグが付与されており、DISABLED_TAGS で無効化できます：objects、search、changelog、status、graphql、ipam、dcim、config、branching、write、delete。読み取りツールには read-only も付与されています。

🔒 セキュリティと安全機能

読み取り専用モード

読み取り専用モードでは、すべての書き込みツールが非表示になり、クライアントには 11 個の読み取りツールのみが表示されます（ブランチ機能が有効な場合は 12 個）。

READ_ONLY_MODE=true

ドライランモード

ドライランモードでは書き込みツールは表示されたままですが、NetBox に変更を加えることはありません。各ツールは対象を特定して検証した後、送信するはずだったリクエストを "dry_run": true のフラグ付きで返します。更新と削除では現在のオブジェクトも取得するため、プレビューには変更される値と削除される内容が正確に表示されます。

DRY_RUN_MODE=true

READ_ONLY_MODE が優先されます。両方が設定されている場合、書き込みツールは非表示になります。

NetBox のブランチ機能

netbox-branching プラグインを使用すると、変更をブランチにステージングし、main にマージする前にレビューできます。ブランチ機能はデフォルトで無効になっているため、プラグインのない NetBox ではブランチ関連のツールも branch 引数も利用できません。次のようにして有効にします。

NETBOX_BRANCHING_ENABLED=true

これにより、netbox_list_branches と netbox_create_branch が追加され、ほかのすべてのツールに branch 引数（ブランチ名またはスキーマ ID）も追加されます。すべての呼び出しの送信先をデフォルトで1つのブランチにするには、次のようにします。

NETBOX_BRANCH=assistant-changes

NETBOX_BRANCHING_ENABLED=true を設定せずに NETBOX_BRANCH を設定すると、設定エラーになります。サーバーは main への書き込みを黙って行うのではなく、起動を拒否します。

ブランチ名は、X-NetBox-Branch ヘッダーで必要となるスキーマ ID に解決されます。マージ、同期、取り消しは意図的にツールとして公開していません。これらは人によるレビューの手順で行うものです。

プラグインの検出

NETBOX_PLUGIN_DISCOVERY=true

未知のタイプを指定する呼び出しが初めて行われたとき（または netbox_list_object_types が実行されたとき）、サーバーは /api/core/object-types/ を読み込み、REST エンドポイントを持つすべてのプラグインモデル（たとえば netbox_dns.zone）を追加します。プラグインのタイプがコアタイプを上書きすることはありません。検出に失敗しても、コアタイプは引き続き機能します。

タグベースのツールフィルタリング

無効にするタグを設定することで、特定のカテゴリのツールを無効にできます。たとえば、作成と更新は許可し、削除は常に禁止するには、次のようにします。

DISABLED_TAGS=delete

レスポンスサイズの上限

NetBox オブジェクトはすぐにサイズが大きくなります。RESPONSE_MAX_SIZE は、指定したバイト数を超えるツールレスポンスを切り詰めます。

RESPONSE_MAX_SIZE=200000

大規模なツールセット向けのツール検索

FastMCP のツール検索を使うと、多数のツールを持つサーバーでプロンプトサイズを削減できます。 有効にすると、list_tools は次の2つの合成ツールを返します。

• search_tools：一致するツールを検索し、完全なスキーマを返します
• call_tool：検出した任意のツールを名前で実行します

次のようにして有効にします。

TOOL_SEARCH_ENABLED=true
TOOL_SEARCH_STRATEGY=bm25      # bm25 or regex
TOOL_SEARCH_MAX_RESULTS=8      # optional, default is 5

bm25 は自然言語のクエリに対応し、regex は決定的なマッチングに pattern 入力として正規表現を使用します。

ツール検索は、既存の表示制御（読み取り専用モードと無効化されたタグ）を尊重します。

レート制限

サーバーは、API の使用量を制御して不正利用を防ぐためのレート制限に対応しています。有効にすると、スライディングウィンドウアルゴリズムを使用して、クライアントごとにリクエスト数を制限します。

.env ファイルで次の環境変数を設定して、レート制限を有効にします。

RATE_LIMIT_ENABLED=true
RATE_LIMIT_MAX_REQUESTS=60    # Maximum requests allowed per window (default: 60)
RATE_LIMIT_WINDOW_MINUTES=1   # Window size in minutes

RATE_LIMIT_ENABLED が true に設定されている場合、サーバーはレート制限ミドルウェアを適用します。環境に応じて RATE_LIMIT_MAX_REQUESTS と RATE_LIMIT_WINDOW_MINUTES を調整してください。

Sentry によるエラー追跡とモニタリング（任意）

サーバーは、エラー追跡、パフォーマンスモニタリング、デバッグに Sentry を任意で利用できます。Sentry との連携は完全に任意であり、設定されている場合にのみ初期化されます。

インストール

Sentry によるモニタリングを有効にするには、オプションの依存関係をインストールします。

# Using UV (recommended)
uv sync --extra sentry

設定

.env ファイルで SENTRY_DSN 環境変数を設定して、Sentry を有効にします。

# Required: Sentry DSN for your project
SENTRY_DSN=https://[email protected]/6789

# Optional: Performance monitoring sample rate (0.0-1.0, default: 1.0)
SENTRY_TRACES_SAMPLE_RATE=1.0

# Optional: Include personally identifiable information (default: false).
# When true, tool inputs and outputs (NetBox inventory data) are sent to Sentry.
SENTRY_SEND_DEFAULT_PII=false

# Optional: Environment name (e.g., "production", "staging")
SENTRY_ENVIRONMENT=production

# Optional: Release version (auto-detected from package if not set)
SENTRY_RELEASE=1.2.3

# Optional: Profiling - continuous profiling sample rate (0.0-1.0, default: 1.0)
SENTRY_PROFILE_SESSION_SAMPLE_RATE=1.0

# Optional: Profiling - lifecycle mode for profiling (default: "trace")
# Options: "all", "continuation", "trace"
SENTRY_PROFILE_LIFECYCLE=trace

# Optional: Enable log capture as breadcrumbs and events (default: true)
SENTRY_ENABLE_LOGS=true

機能

有効にすると、Sentry は次の情報を自動的に収集します。

• 例外とエラー：コンテキスト全体を含む、未処理のすべての例外
• パフォーマンス指標：リクエスト／レスポンス時間とトレース
• MCP 連携：MCP サーバーのアクティビティとインタラクションの詳細
• ログとパンくずリスト：デバッグ用のアプリケーションログとイベント履歴
• コンテキストデータ：環境、クライアント情報、リクエストパラメーター

Sentry DSN の取得

1. sentry.io で無料アカウントを作成します
2. 新しい Python プロジェクトを作成します
3. プロジェクト設定から DSN をコピーします
4. .env ファイルに設定します

Sentry の無効化

Sentry の利用は完全に任意です。SENTRY_DSN を設定しない場合、サーバーは Sentry との連携なしで通常どおり実行され、モニタリングデータは収集されません。

SSL/TLS の設定

サーバーは SSL 証明書の検証と、タイムアウトのカスタム設定に対応しています。

NETBOX_VERIFY_SSL=true    # Enable SSL certificate verification
NETBOX_TIMEOUT=30         # Total time per request, retries included (seconds)

証明書はオペレーティングシステムの信頼ストアを使って検証されるため、NetBox が内部 CA の背後にある場合でも、その CA が OS によって信頼されていればそのまま利用できます。SSL_CERT_FILE または SSL_CERT_DIR が設定されている場合は、そちらが優先されます。

トランスポートの設定

サーバーは MCP プロトコル向けに、複数のトランスポート方式に対応しています。

STDIO トランスポート（デフォルト）

デフォルトのトランスポートでは、標準入力／標準出力を使って通信します。ローカルでの使用や、stdin／stdout 経由で通信するツールとの連携に適しています。

MCP_TRANSPORT=stdio

HTTP SSE トランスポート（サーバー送信イベント）

ネットワークベースでデプロイする場合は、サーバー送信イベントを使った HTTP を利用できます。これにより、MCP サーバーに HTTP 経由でアクセスし、リアルタイムでストリーミングできます。

MCP_TRANSPORT=sse
MCP_HTTP_HOST=127.0.0.1        # Localhost
MCP_HTTP_PORT=8000           # Port to listen on
MCP_HTTP_BEARER_TOKEN=your-secret-token  # Optional authentication token

SSE トランスポートでベアラートークンを使用する場合、クライアントはリクエストにトークンを含める必要があります。

curl -H "Authorization: Bearer your-secret-token" http://localhost:8000/sse

HTTP Streamable トランスポート

HTTP Streamable トランスポートでは、リクエスト／レスポンスのストリーミングを伴う HTTP ベースの通信を行います。ウェブ連携や HTTP エンドポイントを必要とするツールに適しています。

MCP_TRANSPORT=http
MCP_HTTP_HOST=127.0.0.1        # Localhost
MCP_HTTP_PORT=8000           # Port to listen on
MCP_HTTP_BEARER_TOKEN=your-secret-token  # Optional authentication token

ストリーマブルトランスポートでベアラートークンを使用する場合：

curl -H "Authorization: Bearer your-secret-token" \
     -H "Accept: application/json, text/event-stream" \
     -H "Content-Type: application/json" \
     -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' \
     http://localhost:8000/mcp

ユーザーごとの NetBox トークン

デフォルトでは、すべてのクライアントがサーバーの NETBOX_TOKEN を共有するため、NetBox からは 1 人のユーザーとして認識されます。NETBOX_TOKEN_PASSTHROUGH=true を設定すると、各クライアントはそれぞれの NetBox API トークンを送信するようになります。NetBox はそのユーザーの権限を適用し、変更履歴には実際のユーザーが記録されます。

MCP_TRANSPORT=http
MCP_HTTP_HOST=0.0.0.0
NETBOX_TOKEN_PASSTHROUGH=true

claude mcp add --transport http netbox https://netbox-mcp.example.com/mcp \
  --header "Authorization: Bearer nbt_your-key.your-token"

• トークンがないリクエストや、NetBox に拒否されたトークンを含むリクエストには、HTTP 401 が返されます。トークンの確認中に NetBox に 10 秒以内（または、それより短い NETBOX_TIMEOUT の時間内）に到達できない場合、リクエストには Retry-After を付けた HTTP 503 が返されます。これにより、クライアントは再度ログインするのではなく、リトライします。NetBox から Retry-After が送信された場合、HTTP 503 にその値が引き継がれます。受け入れられたトークンは 60 秒間キャッシュされます。その後も、サーバーがバックグラウンドで NetBox に再確認する間、最大 10 分間はトークンがすぐに受け入れられるため、NetBox が停止している場合でも、既知のユーザーが確認を待たされることはありません。再確認の結果が返ると、失効済みのトークンは破棄されます。それまでは、NetBox を呼び出さないツール（ツール一覧など）にのみアクセスできます。NetBox を呼び出すツールでは、NetBox が毎回そのトークンを拒否するためです。拒否されたトークンは 30 秒間キャッシュされます。そのため、NetBox で作成されたばかりのトークンは、作成前に試行されていた場合、最大 30 秒間拒否されることがあります。同時に NetBox に到達するトークン確認は最大 8 件です。サーバーがまだ確認したことのないトークンを含むリクエストは、空き枠ができるまで待機し、確認タイムアウトを超えて待機した場合は HTTP 503 が返されます。
• v2（nbt_...）と従来の v1 トークンの両方が使えます。サーバーは、それぞれを適切なスキームで NetBox に送信します。
• NETBOX_TOKEN は無視されます。対応しているのは http と sse の各トランスポートのみです。また、MCP_HTTP_BEARER_TOKEN も設定されている場合は、どちらも Authorization ヘッダーを使用するため、サーバーは起動を拒否します。
• RATE_LIMIT_ENABLED=true の場合、NetBox の各ユーザー（NetBox 4.5 より前では各トークン）に個別のレート制限ウィンドウが適用されるため、制限によってサーバー全体の NetBox 負荷が上限に達することはなくなります。
• NETBOX_PLUGIN_DISCOVERY=true の場合、任意のユーザーのトークンで見つかったプラグインタイプが、共有リストに追加されます。rediscover は、その呼び出し元のユーザーが確認できる内容でリストを置き換えるため、アンインストール済みのプラグインは削除されます。別のユーザーが、そのユーザーにしか見えないタイプを指定して呼び出すと、そのユーザーのトークンで再検出されます。
• クライアントは NetBox トークンをこのサーバーに送信するため、HTTPS の背後に配置してください。

注：HTTP トランスポートでは、jsonrpc フィールドと id フィールドを含む適切な JSON-RPC 形式が必要です。また、一部の操作ではサーバーセッションの初期化が必要になる場合があります。

ヘルスエンドポイント

どちらの HTTP トランスポート（sse と http）も GET /health を提供し、サーバーがリクエストを処理している場合は 200 ok を返します。ベアラートークンは不要で、NetBox に接続しないため、NetBox が停止しても MCP サーバーが異常と判定されることはありません。 Docker イメージの HEALTHCHECK はこれを使用します：

curl http://localhost:8000/health

FastMCP トランスポートの詳細については、FastMCP のドキュメントをご覧ください。

🤝 貢献

貢献を歓迎します。開発環境のセットアップ、チェック、コミットメッセージの形式についてはCONTRIBUTING.mdをご覧ください。バグや機能リクエストにはイシューテンプレートをご利用ください。

セキュリティ上の問題を見つけた場合は、SECURITY.mdの説明に従って、非公開でご報告ください。

📜 ライセンス

MIT License — 詳細についてはLICENSEをご覧ください。