API Reference - randygagnon/netbox-mcp-server GitHub Wiki

API Reference

The NetBox MCP Server provides a comprehensive set of tools for interacting with NetBox data, including both read and write operations:

Tools

1. get_objects

Retrieves objects from NetBox based on their type and filters.

def get_objects(object_type: str, filters: dict)

Parameters

object_type: String representing the NetBox object type
filters: Dictionary of filters to apply to the API call

Supported Object Types

DCIM (Device and Infrastructure)

cables
console-ports
console-server-ports
devices
device-bays
device-roles
device-types
front-ports
interfaces
inventory-items
locations
manufacturers
modules
module-bays
module-types
platforms
power-feeds
power-outlets
power-panels
power-ports
racks
rack-reservations
rack-roles
regions
sites
site-groups
virtual-chassis

IPAM (IP Address Management)

asns
asn-ranges
aggregates
fhrp-groups
ip-addresses
ip-ranges
prefixes
rirs
roles
route-targets
services
vlans
vlan-groups
vrfs

Circuits

circuits
circuit-types
circuit-terminations
providers
provider-networks

Virtualization

clusters
cluster-groups
cluster-types
virtual-machines
vm-interfaces

Tenancy

tenants
tenant-groups
contacts
contact-groups
contact-roles

VPN

ike-policies
ike-proposals
ipsec-policies
ipsec-profiles
ipsec-proposals
l2vpns
tunnels
tunnel-groups

Wireless

wireless-lans
wireless-lan-groups
wireless-links

2. search_netbox

Performs a global search across NetBox objects.

def search_netbox(query: str, limit: int = 10)

Parameters

query: Search string to look for across NetBox objects
limit: Maximum number of results to return (default: 10)

Returns

List of matching objects across different NetBox models

3. get_object_by_id

Gets detailed information about a specific NetBox object by its ID.

def get_object_by_id(object_type: str, object_id: int)

Parameters

object_type: String representing the NetBox object type
object_id: The numeric ID of the object

Returns

Complete object details

4. create_object

Creates a new object in NetBox.

def create_object(object_type: str, data: dict)

Parameters

object_type: String representing the NetBox object type
data: Dictionary containing the object properties to create

Returns

The created object details

Example

Creating a new device:

data = {
    "name": "new-device",
    "device_type": 1,
    "device_role": 1,
    "site": 1,
    "status": "active"
}
new_device = create_object("devices", data)

5. update_object

Updates an existing object in NetBox.

def update_object(object_type: str, object_id: int, data: dict)

Parameters

object_type: String representing the NetBox object type
object_id: The numeric ID of the object to update
data: Dictionary containing the object properties to update

Returns

The updated object details

Example

Updating a device:

data = {
    "name": "updated-device-name",
    "status": "planned"
}
updated_device = update_object("devices", 123, data)

6. delete_object

Deletes an object from NetBox.

def delete_object(object_type: str, object_id: int)

Parameters

object_type: String representing the NetBox object type
object_id: The numeric ID of the object to delete

Returns

True if deletion was successful, False otherwise

Example

result = delete_object("ip-addresses", 456)

7. bulk_create_objects

Creates multiple objects in NetBox in a single API call.

def bulk_create_objects(object_type: str, data_list: list)

Parameters

object_type: String representing the NetBox object type
data_list: List of dictionaries, each containing the properties for one object to create

Returns

List of created objects

Example

Creating multiple IP addresses:

data_list = [
    {
        "address": "192.168.100.1/24",
        "status": "active",
        "description": "Example IP 1"
    },
    {
        "address": "192.168.100.2/24",
        "status": "active",
        "description": "Example IP 2"
    }
]
new_ips = bulk_create_objects("ip-addresses", data_list)

8. bulk_update_objects

Updates multiple objects in NetBox in a single API call.

def bulk_update_objects(object_type: str, data_list: list)

Parameters

object_type: String representing the NetBox object type
data_list: List of dictionaries, each containing the ID and properties to update

Returns

List of updated objects

Note

Each object dictionary in the data_list MUST contain an 'id' field.

Example

Updating multiple devices:

data_list = [
    {
        "id": 1,
        "status": "planned"
    },
    {
        "id": 2,
        "status": "active"
    }
]
updated_devices = bulk_update_objects("devices", data_list)

9. bulk_delete_objects

Deletes multiple objects from NetBox in a single API call.

def bulk_delete_objects(object_type: str, id_list: list)

Parameters

object_type: String representing the NetBox object type
id_list: List of IDs of objects to delete

Returns

True if deletion was successful, False otherwise

Example

Deleting multiple IP addresses:

id_list = [1, 2, 3]
result = bulk_delete_objects("ip-addresses", id_list)

Example Usage

Get all devices in a site

devices = get_objects("devices", {"site": "DC1"})

Search for a specific device

results = search_netbox("core-switch-01")

Get details of a specific IP address

ip = get_object_by_id("ip-addresses", 123)

Create a new device

new_device = create_object("devices", {
    "name": "new-server",
    "device_type": 5,
    "device_role": 3,
    "site": 1,
    "status": "active"
})

Update a device's status

update_object("devices", 123, {"status": "planned"})

Delete an IP address

delete_object("ip-addresses", 456)

Error Handling

The API will raise exceptions in the following cases:

Invalid object type
Authentication failure
Network connectivity issues
Invalid filters or data
Object not found
Insufficient permissions for write operations

For detailed error handling, refer to the Troubleshooting guide.