NetBox MCP Server

A comprehensive read/write Model Context Protocol server for NetBox network documentation and IPAM systems. Just as our LEGO parrot mascot symbolically mimics human speech, this server allows you to "talk" to your NetBox infrastructure using natural language through LLMs that support MCP.

✨ Key Features

• 142+ MCP Tools: Complete DCIM, IPAM, tenancy, extras, system, and virtualization management with dual-tool pattern architecture
• 🦜 Bridget - Your NetBox Infrastructure Guide
  • Auto-Context Detection - Intelligent environment detection (demo/staging/production)
  • Safety Guidance - Context-aware operational recommendations
  • Persona-Based Assistance - Friendly, professional infrastructure guidance
  • Enterprise Safety - Automatic safety level assignment based on environment
• 🔐 Safety First: Built-in dry-run mode, confirmation requirements, and audit logging
• 🏗️ Self-Describing: Automatic tool discovery with REST API endpoints
• ⚡ Enterprise Hardening: Production-ready secrets management and structured logging
• 📊 Performance Optimized: TTL-based caching with 33%+ performance improvements
• 🔄 Write Operations: Full read/write capabilities with idempotent operations
• 🐳 Docker Ready: Enterprise-grade containerization with health checks

🚀 Quick Start

Docker (Recommended)

docker run -d \
  --name netbox-mcp \
  -e NETBOX_URL="https://your-netbox.example.com" \
  -e NETBOX_TOKEN="your-api-token" \
  -p 8080:8080 \
  controlaltautomate/netbox-mcp:latest

Python Installation

git clone https://github.com/Deployment-Team/netbox-mcp.git
cd netbox-mcp
pip install .

Bridget Auto-Context Experience

For the optimal Bridget experience with full auto-context and persona guidance:

• Recommended: Use Claude Code CLI for complete functionality
• Alternative: Claude Desktop (tools work, limited prompt support)

See the Bridget Documentation in our wiki for complete usage guide.

📊 Current Status

Version: 1.1.2 - Documentation & Version Sync! ⭐

🎉 NEW: MANAGEMENT IP SUITE: Complete out-of-band and primary IP management tools for enterprise device automation:

• netbox_create_interface with mgmt_only parameter for BMC/iDRAC/Console interfaces
• Enhanced netbox_update_device with oob_ip, primary_ip4, primary_ip6 support
• netbox_set_primary_ip with flexible IP resolution and device validation

✅ PRODUCTION READY: All management IP workflows tested against NetBox 4.3.2 with comprehensive bug fixes and enterprise safety features.

🔧 COMPREHENSIVE COVERAGE: 142+ production-ready tools across six domains:

• DCIM Tools (73): Complete device and infrastructure lifecycle management with power management and management IP support
• Virtualization Tools (30): Complete VM infrastructure management (NEW) ⭐
• IPAM Tools (16): IP address and network management with enterprise automation
• Tenancy Tools (8): Multi-tenant resource management with hierarchical organization
• Extras Tools (2): Journal entries and audit trail management
• System Tools (1): Health monitoring and system status

🚀 DISCOVERY TOOLS: 23+ list_all_* tools enabling efficient bulk exploration:

• netbox_list_all_devices, netbox_list_all_sites, netbox_list_all_racks, netbox_list_all_power_panels, netbox_list_all_power_feeds, netbox_list_all_power_outlets, netbox_list_all_power_cables, netbox_list_all_module_type_profiles (DCIM)
• netbox_list_all_prefixes, netbox_list_all_vlans, netbox_list_all_vrfs (IPAM)
• netbox_list_all_tenants, netbox_list_all_tenant_groups (Tenancy)
• netbox_list_all_manufacturers, netbox_list_all_device_types, netbox_list_all_device_roles (Device Management)

🛡️ ENTERPRISE FOUNDATION: Defensive Read-Validate-Write Pattern with Registry Bridge ensuring 100% tool accessibility and conflict detection accuracy.

⚙️ Configuration

Quick Setup: Set required environment variables:

• NETBOX_URL: Full URL to your NetBox instance
• NETBOX_TOKEN: API token from NetBox

Advanced Configuration: Use YAML/TOML configuration files or additional environment variables for enterprise features like secrets management and structured logging.

🔒 Safety & Enterprise Features

CRITICAL SAFETY CONTROLS: This MCP server can perform write operations on NetBox data:

• ✅ Idempotent Operations: All write tools are idempotent by design
• ✅ Confirmation Required: confirm=True parameter for all write operations
• ✅ Global Dry-Run Mode: NETBOX_DRY_RUN=true for testing
• ✅ Audit Logging: Comprehensive logging of all operations
• ✅ Transaction Safety: Atomic operations with rollback capabilities

🏗️ Architecture Highlights

Revolutionary Dual-Tool Pattern

• Fundamental LLM Architecture: Every NetBox domain implements both "info" tools (detailed single-object retrieval) and "list_all" tools (bulk discovery/exploration)
• Comprehensive Filtering: All list tools support filtering by site, tenant, status, and domain-specific criteria
• Summary Statistics: Rich aggregate statistics, breakdowns, and utilization metrics for operational insight
• Cross-Domain Integration: Tools bridge DCIM, IPAM, and Tenancy domains with relationship tracking

Revolutionary Self-Describing Server

• @mcp_tool Decorator: Automatic function inspection and metadata generation
• Plugin Architecture: Modular tools/ subpackage with automatic discovery
• Registry Bridge Pattern: Seamless connection between internal registry and FastMCP interface
• Dependency Injection: Clean separation using FastAPI's Depends() system
• REST API Endpoints: /api/v1/tools, /api/v1/execute, /api/v1/status

Bridget Auto-Context Layer

Auto-Context Detection → Environment Assessment → Safety Assignment → Persona Guidance

Enterprise Security & Operations

• Secrets Management: Docker secrets, Kubernetes secrets, environment variables
• Structured Logging: JSON logging compatible with ELK Stack, Splunk, Datadog
• Performance Monitoring: Correlation IDs, operation timing, cache statistics

📚 Documentation

• Complete Wiki - Comprehensive documentation with examples
• API Reference - Complete tool documentation
• Installation Guide - Setup and deployment
• Docker Guide - Container deployment
• Enterprise Showcase - Real-world use cases

📋 Requirements

• Python 3.10+
• NetBox 3.5+ or newer (REST API v2.8+ support)
• Valid NetBox API token with appropriate permissions

🚀 Available Tools

System Tools (1):

• netbox_health_check - Comprehensive health check

IPAM Tools (12):

• netbox_create_ip_address - Create IP address assignments
• netbox_find_available_ip - Find available IPs in network
• netbox_get_ip_usage - Network utilization statistics
• netbox_create_prefix - Create network prefixes
• netbox_create_vlan - Create VLANs
• netbox_find_available_vlan_id - Find available VLAN IDs
• netbox_create_vrf - Create VRF instances
• netbox_assign_mac_to_interface - 🆕 Enterprise MAC address management with defensive conflict detection
• netbox_find_next_available_ip - 🆕 Atomic IP reservation with cross-domain integration
• netbox_get_prefix_utilization - 🆕 Comprehensive capacity planning reports
• netbox_provision_vlan_with_prefix - 🆕 Atomic VLAN/prefix coordination
• netbox_assign_ip_to_interface - 🆕 Cross-domain IPAM/DCIM integration

DCIM Tools (73):

• Core Infrastructure (17 tools):

  • netbox_create_site, netbox_get_site_info - Site management
  • netbox_create_rack, netbox_get_rack_elevation - Rack management
  • netbox_create_manufacturer - Manufacturer management
  • netbox_create_device_type, netbox_get_device_type_info, netbox_update_device_type, netbox_delete_device_type - 🆕 Complete device type CRUD
  • netbox_create_device_role - Device role management
  • netbox_create_device, netbox_get_device_info, netbox_update_device - 🆕 Enhanced device management with management IP support
  • netbox_install_module_in_device - Device component installation
  • netbox_add_power_port_to_device - Power infrastructure documentation

• Management & OOB IP Suite (3 tools) 🆕:

  • netbox_create_interface - 🆕 Interface creation with mgmt_only support for BMC/iDRAC
  • netbox_set_primary_ip - 🆕 Primary IP assignment with intelligent resolution
  • Enhanced netbox_update_device with oob_ip, primary_ip4, primary_ip6 parameters

• Module Type Profiles (6 tools) 🆕 NetBox 4.3.x:

  • netbox_create_module_type_profile, netbox_get_module_type_profile_info, netbox_list_all_module_type_profiles
  • netbox_update_module_type_profile, netbox_delete_module_type_profile, netbox_assign_module_type_profile

• Module Management (2 enhanced tools) 🆕:

  • netbox_update_module_type, netbox_delete_module_type - Complete module type CRUD

• Power Management Infrastructure (19 tools) 🆕:

  • Power Panels (5): netbox_create_power_panel, netbox_get_power_panel_info, netbox_list_all_power_panels, netbox_update_power_panel, netbox_delete_power_panel
  • Power Feeds (5): netbox_create_power_feed, netbox_get_power_feed_info, netbox_list_all_power_feeds, netbox_update_power_feed, netbox_delete_power_feed
  • Power Outlets (5): netbox_create_power_outlet, netbox_get_power_outlet_info, netbox_list_all_power_outlets, netbox_update_power_outlet, netbox_delete_power_outlet
  • Power Connections (4): netbox_create_power_cable, netbox_get_power_connection_info, netbox_list_all_power_cables, netbox_disconnect_power_cable

• Inventory Management Suite (7 tools):

  • netbox_add_inventory_item_template_to_device_type, netbox_list_inventory_item_templates_for_device_type
  • netbox_add_inventory_item_to_device, netbox_list_device_inventory, netbox_update_inventory_item
  • netbox_remove_inventory_item, netbox_bulk_add_standard_inventory

Tenancy Tools (8):

• netbox_create_contact_for_tenant - 🆕 Contact management with role-based assignment
• netbox_onboard_new_tenant - Complete tenant onboarding with contact integration
• netbox_create_tenant_group - Hierarchical tenant organization
• netbox_assign_resources_to_tenant - Cross-domain resource assignment
• netbox_get_tenant_resource_report - Comprehensive tenant resource reporting
• netbox_list_all_tenants - Bulk tenant discovery
• netbox_list_all_tenant_groups - Tenant group exploration

Extras Tools (2):

• netbox_create_journal_entry - 🆕 Create audit trail entries for any NetBox object
• netbox_list_all_journal_entries - 🆕 Bulk journal entry discovery with filtering

Virtualization Tools (30) ⭐ NEW:

• Clusters (5 tools): netbox_create_cluster, netbox_get_cluster_info, netbox_list_all_clusters, netbox_update_cluster, netbox_delete_cluster
• Virtual Machines (5 tools): netbox_create_virtual_machine, netbox_get_virtual_machine_info, netbox_list_all_virtual_machines, netbox_update_virtual_machine, netbox_delete_virtual_machine
• Cluster Types (5 tools): netbox_create_cluster_type, netbox_get_cluster_type_info, netbox_list_all_cluster_types, netbox_update_cluster_type, netbox_delete_cluster_type
• Cluster Groups (5 tools): netbox_create_cluster_group, netbox_get_cluster_group_info, netbox_list_all_cluster_groups, netbox_update_cluster_group, netbox_delete_cluster_group
• VM Interfaces (5 tools): netbox_create_vm_interface, netbox_get_vm_interface_info, netbox_list_all_vm_interfaces, netbox_update_vm_interface, netbox_delete_vm_interface
• Virtual Disks (5 tools): netbox_create_virtual_disk, netbox_get_virtual_disk_info, netbox_list_all_virtual_disks, netbox_update_virtual_disk, netbox_delete_virtual_disk

🤝 Contributing

This project is under active development. See our GitHub Issues for:

• Current development priorities
• Feature requests and roadmap
• Bug reports and discussions

📄 License

MIT License - see LICENSE file for details.

🔗 Related Projects

• Enterprise network automation tools - Production-ready MCP servers
• NetBox - The network documentation and IPAM application

---

⚠️ Development Notice: This is a development version with write capabilities. Always use proper safety measures and test in non-production environments.