NetBox MCP Server

NetBox MCP サーバー

⚠️ v1.0.0 の破壊的変更：プロジェクトの構成が変更されました。 v0.1.0 からアップグレードする場合は、設定を更新してください。

• uv run server.py を uv run netbox-mcp-server に変更します
• Claude Desktop／Code の設定で、server.py の代わりに netbox-mcp-server を使用します
• Docker ユーザー：更新された CMD でイメージを再ビルドします
• 詳細については、CHANGELOG.md を参照してください

これは、NetBox 用のシンプルな読み取り専用 Model Context Protocol サーバーです。MCP をサポートする LLM を通じて、NetBox のデータを直接操作できます。

このサーバーは、意図的にシンプルな設計にしています。簡単に使い始められ、誤用しにくく（デフォルトで読み取り専用、プラグインの拡張ポイントなし）、フォークして適応しやすい構成です。プロジェクトの範囲を超える機能が必要なユーザーにとって、Apache 2.0 のもとでフォークすることは、正式に想定された選択肢です。

コミュニティ

チャット、ユースケース、MCP 全般に関する話題については、netdev.chat の NetBox コミュニティに参加してください。MCP 統合、質問、ユースケースの共有には #ai チャンネルをご利用ください。このサーバー固有のバグや機能のアイデアは、issues に投稿してください。

ツール

ツール	説明
get_objects	種類とフィルターに基づいて、NetBox のコアオブジェクトを取得します
get_object_by_id	ID を指定して、特定の NetBox オブジェクトの詳細情報を取得します
get_changelogs	フィルターに基づいて、変更履歴レコード（監査証跡）を取得します

注：NetBox のコアオブジェクトタイプは常に利用できます。プラグインのオブジェクトタイプは自動検出できます。プラグインオブジェクトタイプの検出を参照してください。高度な機能（GraphQL、動的なモデル検出など）は、意図的に対象外としています。対象範囲とその理由について詳しくは、CONTRIBUTING.md を参照してください。

使い方

1. MCP を通じて利用可能にするデータにツールがアクセスできるよう、十分な権限を持つ読み取り専用 API トークンを NetBox で作成します。

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

   # UV を使用する場合（推奨）
   uv sync
   
   # または pip を使用する場合
   pip install -e .
   

3. サーバーを実行できることを確認します：NETBOX_URL=https://netbox.example.com/ NETBOX_TOKEN=<your-api-token> uv run netbox-mcp-server

4. MCP サーバーを LLM クライアントに追加します。Claude を使った例については、以下を参照してください。

Claude Code

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

claude mcp add コマンドを使ってサーバーを追加します。

claude mcp add --transport stdio netbox \
  --env NETBOX_URL=https://netbox.example.com/ \
  --env NETBOX_TOKEN=<your-api-token> \
  -- uv --directory /path/to/netbox-mcp-server run netbox-mcp-server

重要な注意事項：

• /path/to/netbox-mcp-server をローカルのクローンへの絶対パスに置き換えてください
• -- 区切り文字は、Claude Code のフラグとサーバーコマンドを区別します
• --scope project を使用すると、バージョン管理下の .mcp.json を通じて設定を共有できます
• --scope user を使用すると、すべてのプロジェクトで利用できます（デフォルトは local です）

追加後、Claude Code の /mcp またはターミナルの claude mcp list で確認してください。

HTTP トランスポート

HTTP トランスポートを使用する場合は、まずサーバーを手動で起動します。

# Start the server with HTTP transport (using .env or environment variables)
NETBOX_URL=https://netbox.example.com/ \
NETBOX_TOKEN=<your-api-token> \
TRANSPORT=http \
uv run netbox-mcp-server

次に、起動したサーバーを Claude Code に追加します。

# Add the HTTP MCP server (note: URL must include http:// or https:// prefix)
claude mcp add --transport http netbox http://127.0.0.1:8000/mcp

重要な注意事項：

• URL にはプロトコルのプレフィックス（http:// または https://）を必ず含めてください
• HTTP トランスポートを使用する場合、デフォルトのエンドポイントは /mcp です
• Claude Code が接続する前に、サーバーを起動しておく必要があります
• claude mcp list で接続を確認してください。サーバー名の横に ✓ が表示されます

Claude Desktop

サーバーの設定を Claude Desktop の設定ファイルに追加します。Mac では、~/Library/Application Support/Claude/claude_desktop_config.json を編集します。

{
    "mcpServers": {
        "netbox": {
            "command": "uv",
            "args": [
                "--directory",
                "/path/to/netbox-mcp-server",
                "run",
                "netbox-mcp-server"
            ],
            "env": {
                "NETBOX_URL": "https://netbox.example.com/",
                "NETBOX_TOKEN": "<your-api-token>"
            }
        }
    }
}

Windows では、C:\\Users\\myuser\\.local\\bin\\uv や C:\\Users\\myuser\\netbox-mcp-server のように、インスタンスへの完全なエスケープ済みパスを使用してください。 詳しいトラブルシューティングについては、MCP クイックスタートを参照してください。

5. LLM クライアントでツールを使用します。たとえば、次のようにします。

> Get all devices in the 'Equinix DC14' site
...
> Tell me about my IPAM utilization
...
> What Cisco devices are in my network?
...
> Who made changes to the NYC site in the last week?
...
> Show me all configuration changes to the core router in the last month

フィールドのフィルタリング（トークンの最適化）

netbox_get_objects() と netbox_get_object_by_id() は、トークンの使用量を減らすための省略可能な fields パラメーターをサポートしています。

# Without fields: ~5000 tokens for 50 devices
devices = netbox_get_objects("devices", {"site": "datacenter-1"})

# With fields: ~500 tokens (90% reduction)
devices = netbox_get_objects(
    "devices", {"site": "datacenter-1"}, fields=["id", "name", "status", "site"]
)

よく使われるフィールドのパターン：

• デバイス： ['id', 'name', 'status', 'device_type', 'site', 'primary_ip4']
• IP アドレス： ['id', 'address', 'status', 'dns_name', 'description']
• インターフェース： ['id', 'name', 'type', 'enabled', 'device']
• サイト： ['id', 'name', 'status', 'region', 'description']

fields パラメーターは、NetBox のネイティブなフィールドフィルタリングを使用します。詳細については、NetBox API のドキュメントを参照してください。

設定

サーバーは複数の設定ソースをサポートしており、優先順位は次のとおりです（高い順）。

1. コマンドライン引数（最優先）
2. 環境変数
3. プロジェクトルートの .env ファイル
4. デフォルト値（最も低い優先順位）

設定リファレンス

設定	型	デフォルト	必須	説明
NETBOX_URL	URL	-	はい	NetBox インスタンスのベース URL（例：https://netbox.example.com/）
NETBOX_TOKEN	文字列	-	はい	認証用 API トークン
TRANSPORT	stdio | http	stdio	いいえ	MCP トランスポートプロトコル
HOST	文字列	127.0.0.1	HTTP の場合	HTTP サーバーのホストアドレス
PORT	整数	8000	HTTP の場合	HTTP サーバーのポート
MCP_AUTH_TOKEN	文字列	-	いいえ	HTTP エンドポイントで必要となるベアラートークン。未設定の場合、HTTP トランスポートは認証なしになります。クライアントは Authorization: Bearer <token> を送信します。
VERIFY_SSL	ブール値	true	いいえ	SSL 証明書を検証するかどうか
ENABLE_PLUGIN_DISCOVERY	ブール値	false	いいえ	起動時にプラグインのオブジェクトタイプを自動検出するかどうか
LOG_LEVEL	DEBUG | INFO | WARNING | ERROR | CRITICAL	INFO	いいえ	ログの詳細度

トランスポートの例

Stdio トランスポート（Claude Desktop／Code）

stdio トランスポートを使用して Claude Desktop または Claude Code をローカルで利用する場合：

{
    "mcpServers": {
        "netbox": {
            "command": "uv",
            "args": ["--directory", "/path/to/netbox-mcp-server", "run", "netbox-mcp-server"],
            "env": {
                "NETBOX_URL": "https://netbox.example.com/",
                "NETBOX_TOKEN": "<your-api-token>"
            }
        }
    }
}

HTTP トランスポート（Web クライアント）

HTTP/SSE トランスポートを使用する Web ベースの MCP クライアントの場合：

# Using environment variables
export NETBOX_URL=https://netbox.example.com/
export NETBOX_TOKEN=<your-api-token>
export TRANSPORT=http
export HOST=127.0.0.1
export PORT=8000

uv run netbox-mcp-server

# Or using CLI arguments
uv run netbox-mcp-server \
  --netbox-url https://netbox.example.com/ \
  --netbox-token <your-api-token> \
  --transport http \
  --host 127.0.0.1 \
  --port 8000

.env ファイルの例

プロジェクトルートに .env ファイルを作成します。

# Core NetBox Configuration
NETBOX_URL=https://netbox.example.com/
NETBOX_TOKEN=your_api_token_here

# Transport Configuration (optional, defaults to stdio)
TRANSPORT=stdio

# HTTP Transport Settings (only used if TRANSPORT=http)
# HOST=127.0.0.1
# PORT=8000
# Bearer token required on the HTTP endpoint. When unset, the endpoint is unauthenticated.
# MCP_AUTH_TOKEN=a-strong-random-token

# Security (optional, defaults to true)
VERIFY_SSL=true

# Plugin Discovery (optional, defaults to false)
# ENABLE_PLUGIN_DISCOVERY=true

# Logging (optional, defaults to INFO)
LOG_LEVEL=INFO

CLI 引数

すべての設定オプションは、CLI 引数で上書きできます。

uv run netbox-mcp-server --help

# Common examples:
uv run netbox-mcp-server --log-level DEBUG --no-verify-ssl  # Development
uv run netbox-mcp-server --transport http --port 9000       # Custom HTTP port

Docker の使用方法

ビルド済みイメージ（Docker Hub）

ビルド済みのマルチアーキテクチャイメージ（linux/amd64、linux/arm64）は、タグ付きリリースごとに Docker Hub に公開されます。

docker pull netboxlabs/netbox-mcp-server:latest

本番環境では、特定のバージョンを指定してください。latest タグは最新リリースを指しており、予告なく変更される場合があります。利用可能なバージョンについては、リリースページを参照してください。

docker pull netboxlabs/netbox-mcp-server:<X.Y.Z>   # exact version
docker pull netboxlabs/netbox-mcp-server:<X.Y>     # latest within a minor
docker pull netboxlabs/netbox-mcp-server:<X>       # latest within a major

イメージの来歴を検証する（省略可能ですが、推奨）。 イメージは cosign で署名されており（GitHub OIDC を介したキーレス署名）、SLSA ビルド来歴情報が含まれています。

cosign verify \
  --certificate-identity-regexp '^https://github.com/netboxlabs/netbox-mcp-server/' \
  --certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \
  netboxlabs/netbox-mcp-server:<tag>

標準 Docker イメージ

NetBox MCP サーバーをコンテナ内でビルドして実行します。

# Build the image
docker build -t netbox-mcp-server:latest .

# Run with HTTP transport (required for Docker containers)
docker run --rm \
  -e NETBOX_URL=https://netbox.example.com/ \
  -e NETBOX_TOKEN=<your-api-token> \
  -e TRANSPORT=http \
  -e HOST=0.0.0.0 \
  -e PORT=8000 \
  -e MCP_AUTH_TOKEN=<a-strong-random-token> \
  -p 8000:8000 \
  netbox-mcp-server:latest

注記： Docker コンテナでは、TRANSPORT=http が必要です。stdio トランスポートはコンテナ化された環境では動作しません。

⚠️ セキュリティ： MCP_AUTH_TOKEN を設定しない限り、HTTP トランスポートには認証がありません。HOST=0.0.0.0 にバインドすると、そのポートにアクセスできるすべてのユーザーに、トークンで参照可能な NetBox データが読み取り可能な状態で公開されます。強力な MCP_AUTH_TOKEN を設定し（クライアントは Authorization: Bearer <token> を送信します）、サーバーをネットワークに公開する前に、リバースプロキシまたはゲートウェイで TLS を終端してください。プレーン HTTP で送信されたベアラートークンは傍受される可能性があるため、実際のデプロイでは TLS が必要です。

ホストマシン上の NetBox に接続する場合：

NetBox インスタンスがホストマシン上（コンテナ内ではなく）で実行されている場合、macOS と Windows では localhost の代わりに host.docker.internal を使用する必要があります。

# For NetBox running on host (macOS/Windows)
docker run --rm \
  -e NETBOX_URL=http://host.docker.internal:18000/ \
  -e NETBOX_TOKEN=<your-api-token> \
  -e TRANSPORT=http \
  -e HOST=0.0.0.0 \
  -e PORT=8000 \
  -e MCP_AUTH_TOKEN=<a-strong-random-token> \
  -p 8000:8000 \
  netbox-mcp-server:latest

注記： Linux では、代わりに --network host を使用するか、ホストの IP アドレスを直接指定できます。

追加の設定オプションを使用する場合：

docker run --rm \
  -e NETBOX_URL=https://netbox.example.com/ \
  -e NETBOX_TOKEN=<your-api-token> \
  -e TRANSPORT=http \
  -e HOST=0.0.0.0 \
  -e MCP_AUTH_TOKEN=<a-strong-random-token> \
  -e LOG_LEVEL=DEBUG \
  -e VERIFY_SSL=false \
  -p 8000:8000 \
  netbox-mcp-server:latest

サーバーは MCP クライアントから http://localhost:8000/mcp でアクセスできます。お好みの方法で接続できます。

プラグインオブジェクトタイプの検出

デフォルトでは、コア NetBox オブジェクトタイプのみを使用できます。NetBox インスタンスにプラグイン（例：netbox-dns、netbox-inventory）がインストールされている場合、自動検出を有効にして、それらのオブジェクトタイプも利用できるようにできます。

検出の有効化

ENABLE_PLUGIN_DISCOVERY 環境変数を設定するか、--enable-plugin-discovery CLI フラグを使用します。

# Via environment variable
ENABLE_PLUGIN_DISCOVERY=true uv run netbox-mcp-server

# Via CLI flag
uv run netbox-mcp-server --enable-plugin-discovery

# In Claude Desktop config
{
    "mcpServers": {
        "netbox": {
            "command": "uv",
            "args": ["--directory", "/path/to/netbox-mcp-server", "run", "netbox-mcp-server"],
            "env": {
                "NETBOX_URL": "https://netbox.example.com/",
                "NETBOX_TOKEN": "<your-api-token>",
                "ENABLE_PLUGIN_DISCOVERY": "true"
            }
        }
    }
}

仕組み

起動時に、サーバーは NetBox の core/object-types API エンドポイント（NetBox < 4.4 では extras/object-types にフォールバック）にクエリを送信し、REST API エンドポイントを持つインストール済みプラグインモデルをすべて検出します。検出されたモデルは、コアタイプとともに実行時のタイプレジストリに追加されます。

検出されたプラグインタイプは、app_label.model 形式の命名規則（例：netbox_dns.zone、netbox_inventory.asset）を使用し、既存のすべてのツール（netbox_get_objects、netbox_get_object_by_id、netbox_search_objects）で利用できます。

要件

• NetBox 4.2 以降
• API トークンに object-types エンドポイントへの読み取りアクセス権があること
• 検出対象のプラグインモデルが REST API エンドポイントを公開していること

検出に失敗した場合の動作

ネットワークエラー、権限不足、未対応の NetBox バージョンなど、何らかの理由で検出に失敗した場合、サーバーは警告をログに記録し、コアタイプのみで処理を続行します。これにより、検出結果にかかわらずサーバーは常に正常に起動します。

開発

コントリビューションを歓迎します！新機能を提案する前に、CONTRIBUTING.md をお読みください。プロジェクトの範囲に合うかどうかを確認するため、まず issue を作成して議論することを推奨します。

ユースケースでこのプロジェクトの範囲外の機能が必要な場合は、Apache 2.0 のもとでフォークする方法を積極的にサポートしています。

ライセンス

このプロジェクトは Apache 2.0 ライセンスのもとでライセンスされています。詳細は LICENSE ファイルをご覧ください。