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_interfacewithmgmt_onlyparameter for BMC/iDRAC/Console interfaces- Enhanced
netbox_update_devicewithoob_ip,primary_ip4,primary_ip6support netbox_set_primary_ipwith 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 instanceNETBOX_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=Trueparameter for all write operations - ✅ Global Dry-Run Mode:
NETBOX_DRY_RUN=truefor 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 assignmentsnetbox_find_available_ip- Find available IPs in networknetbox_get_ip_usage- Network utilization statisticsnetbox_create_prefix- Create network prefixesnetbox_create_vlan- Create VLANsnetbox_find_available_vlan_id- Find available VLAN IDsnetbox_create_vrf- Create VRF instancesnetbox_assign_mac_to_interface- 🆕 Enterprise MAC address management with defensive conflict detectionnetbox_find_next_available_ip- 🆕 Atomic IP reservation with cross-domain integrationnetbox_get_prefix_utilization- 🆕 Comprehensive capacity planning reportsnetbox_provision_vlan_with_prefix- 🆕 Atomic VLAN/prefix coordinationnetbox_assign_ip_to_interface- 🆕 Cross-domain IPAM/DCIM integration
DCIM Tools (73):
-
Core Infrastructure (17 tools):
netbox_create_site,netbox_get_site_info- Site managementnetbox_create_rack,netbox_get_rack_elevation- Rack managementnetbox_create_manufacturer- Manufacturer managementnetbox_create_device_type,netbox_get_device_type_info,netbox_update_device_type,netbox_delete_device_type- 🆕 Complete device type CRUDnetbox_create_device_role- Device role managementnetbox_create_device,netbox_get_device_info,netbox_update_device- 🆕 Enhanced device management with management IP supportnetbox_install_module_in_device- Device component installationnetbox_add_power_port_to_device- Power infrastructure documentation
-
Management & OOB IP Suite (3 tools) 🆕:
netbox_create_interface- 🆕 Interface creation withmgmt_onlysupport for BMC/iDRACnetbox_set_primary_ip- 🆕 Primary IP assignment with intelligent resolution- Enhanced
netbox_update_devicewithoob_ip,primary_ip4,primary_ip6parameters
-
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_profilesnetbox_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
- Power Panels (5):
-
Inventory Management Suite (7 tools):
netbox_add_inventory_item_template_to_device_type,netbox_list_inventory_item_templates_for_device_typenetbox_add_inventory_item_to_device,netbox_list_device_inventory,netbox_update_inventory_itemnetbox_remove_inventory_item,netbox_bulk_add_standard_inventory
Tenancy Tools (8):
netbox_create_contact_for_tenant- 🆕 Contact management with role-based assignmentnetbox_onboard_new_tenant- Complete tenant onboarding with contact integrationnetbox_create_tenant_group- Hierarchical tenant organizationnetbox_assign_resources_to_tenant- Cross-domain resource assignmentnetbox_get_tenant_resource_report- Comprehensive tenant resource reportingnetbox_list_all_tenants- Bulk tenant discoverynetbox_list_all_tenant_groups- Tenant group exploration
Extras Tools (2):
netbox_create_journal_entry- 🆕 Create audit trail entries for any NetBox objectnetbox_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.