NetBox MCP Server

Instructions

Implementation Reference

• server.py:207-228 (handler)

  The main handler function for netbox_get_object_by_id, decorated with @mcp.tool() for registration and execution. It validates the object_type, constructs the API endpoint, and fetches the object details from NetBox.

  @mcp.tool()
  def netbox_get_object_by_id(object_type: str, object_id: int):
      """
      Get detailed information about a specific NetBox object by its ID.
      
      Args:
          object_type: String representing the NetBox object type (e.g. "devices", "ip-addresses")
          object_id: The numeric ID of the object
      
      Returns:
          Complete object details
      """
      # Validate object_type exists in mapping
      if object_type not in NETBOX_OBJECT_TYPES:
          valid_types = "\n".join(f"- {t}" for t in sorted(NETBOX_OBJECT_TYPES.keys()))
          raise ValueError(f"Invalid object_type. Must be one of:\n{valid_types}")
          
      # Get API endpoint from mapping
      endpoint = f"{NETBOX_OBJECT_TYPES[object_type]}/{object_id}"
      
      return netbox.get(endpoint)

• netbox_llm_chatbot.py:71-90 (schema)

  Input schema definition for the netbox_get_object_by_id tool used in the LLM chatbot's tool calling configuration.

      "type": "function",
      "function": {
          "name": "netbox_get_object_by_id",
          "description": "Get detailed information about a specific NetBox object by its ID.",
          "parameters": {
              "type": "object",
              "properties": {
                  "object_type": {
                      "type": "string",
                      "description": "Type of NetBox object"
                  },
                  "object_id": {
                      "type": "integer",
                      "description": "The numeric ID of the object"
                  }
              },
              "required": ["object_type", "object_id"]
          }
      }
  },

• server.py:5-98 (helper)

  Global mapping of NetBox object types to their corresponding API endpoints, used by the netbox_get_object_by_id handler to construct the correct API URL.

  # Mapping of simple object names to API endpoints
  NETBOX_OBJECT_TYPES = {
      # DCIM (Device and Infrastructure)
      "cables": "dcim/cables",
      "console-ports": "dcim/console-ports", 
      "console-server-ports": "dcim/console-server-ports",
      "devices": "dcim/devices",
      "device-bays": "dcim/device-bays",
      "device-roles": "dcim/device-roles",
      "device-types": "dcim/device-types",
      "front-ports": "dcim/front-ports",
      "interfaces": "dcim/interfaces",
      "inventory-items": "dcim/inventory-items",
      "locations": "dcim/locations",
      "manufacturers": "dcim/manufacturers",
      "modules": "dcim/modules",
      "module-bays": "dcim/module-bays",
      "module-types": "dcim/module-types",
      "platforms": "dcim/platforms",
      "power-feeds": "dcim/power-feeds",
      "power-outlets": "dcim/power-outlets",
      "power-panels": "dcim/power-panels",
      "power-ports": "dcim/power-ports",
      "racks": "dcim/racks",
      "rack-reservations": "dcim/rack-reservations",
      "rack-roles": "dcim/rack-roles",
      "regions": "dcim/regions",
      "sites": "dcim/sites",
      "site-groups": "dcim/site-groups",
      "virtual-chassis": "dcim/virtual-chassis",
      
      # IPAM (IP Address Management)
      "asns": "ipam/asns",
      "asn-ranges": "ipam/asn-ranges", 
      "aggregates": "ipam/aggregates",
      "fhrp-groups": "ipam/fhrp-groups",
      "ip-addresses": "ipam/ip-addresses",
      "ip-ranges": "ipam/ip-ranges",
      "prefixes": "ipam/prefixes",
      "rirs": "ipam/rirs",
      "roles": "ipam/roles",
      "route-targets": "ipam/route-targets",
      "services": "ipam/services",
      "vlans": "ipam/vlans",
      "vlan-groups": "ipam/vlan-groups",
      "vrfs": "ipam/vrfs",
      
      # Circuits
      "circuits": "circuits/circuits",
      "circuit-types": "circuits/circuit-types",
      "circuit-terminations": "circuits/circuit-terminations",
      "providers": "circuits/providers",
      "provider-networks": "circuits/provider-networks",
      
      # Virtualization
      "clusters": "virtualization/clusters",
      "cluster-groups": "virtualization/cluster-groups",
      "cluster-types": "virtualization/cluster-types",
      "virtual-machines": "virtualization/virtual-machines",
      "vm-interfaces": "virtualization/interfaces",
      
      # Tenancy
      "tenants": "tenancy/tenants",
      "tenant-groups": "tenancy/tenant-groups",
      "contacts": "tenancy/contacts",
      "contact-groups": "tenancy/contact-groups",
      "contact-roles": "tenancy/contact-roles",
      
      # VPN
      "ike-policies": "vpn/ike-policies",
      "ike-proposals": "vpn/ike-proposals",
      "ipsec-policies": "vpn/ipsec-policies",
      "ipsec-profiles": "vpn/ipsec-profiles",
      "ipsec-proposals": "vpn/ipsec-proposals",
      "l2vpns": "vpn/l2vpns",
      "tunnels": "vpn/tunnels",
      "tunnel-groups": "vpn/tunnel-groups",
      
      # Wireless
      "wireless-lans": "wireless/wireless-lans",
      "wireless-lan-groups": "wireless/wireless-lan-groups",
      "wireless-links": "wireless/wireless-links",
  
      # Extras
      "config-contexts": "extras/config-contexts",
      "custom-fields": "extras/custom-fields",
      "export-templates": "extras/export-templates",
      "image-attachments": "extras/image-attachments",
      "jobs": "extras/jobs",
      "saved-filters": "extras/saved-filters",
      "scripts": "extras/scripts",
      "tags": "extras/tags",
      "webhooks": "extras/webhooks",
  }