leo-claude-mktplace/mcp-servers/netbox/README.md

NetBox MCP Server

MCP (Model Context Protocol) server for essential NetBox API integration with Claude Code.

Overview

This MCP server provides Claude Code with focused access to the NetBox REST API for tracking servers, services, IP addresses, and databases. It has been optimized to include only essential tools:

• DCIM - Sites, Devices (servers/VPS), Interfaces
• IPAM - IP Addresses, Prefixes, Services (applications/databases)
• Virtualization - Clusters, Virtual Machines, VM Interfaces
• Extras - Tags, Journal Entries (audit/notes)

Total: 37 tools (~3,700 tokens) — down from 182 tools (~19,810 tokens).

Installation

1. Clone and Setup

cd /path/to/mcp-servers/netbox
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -r requirements.txt

2. Configure Credentials

Create the system-level configuration file:

mkdir -p ~/.config/claude
cat > ~/.config/claude/netbox.env << 'EOF'
NETBOX_API_URL=https://your-netbox-instance/api
NETBOX_API_TOKEN=your-api-token-here
NETBOX_VERIFY_SSL=true
NETBOX_TIMEOUT=30
EOF

Getting a NetBox API Token:

1. Log into your NetBox instance
2. Navigate to your profile (top-right menu)
3. Go to "API Tokens"
4. Click "Add a token"
5. Copy the generated token

3. Register with Claude Code

Add to your Claude Code MCP configuration (.claude/mcp.json or project-level .mcp.json):

{
  "mcpServers": {
    "netbox": {
      "command": "/path/to/mcp-servers/netbox/.venv/bin/python",
      "args": ["-m", "mcp_server"],
      "cwd": "/path/to/mcp-servers/netbox"
    }
  }
}

Windows:

{
  "mcpServers": {
    "netbox": {
      "command": "C:\\path\\to\\mcp-servers\\netbox\\.venv\\Scripts\\python.exe",
      "args": ["-m", "mcp_server"],
      "cwd": "C:\\path\\to\\mcp-servers\\netbox"
    }
  }
}

Available Tools (37 Total)

DCIM: Sites, Devices, Interfaces (11 tools)

Sites (4):

Tool	Description	Parameters
dcim_list_sites	List sites	name, status
dcim_get_site	Get site by ID	id (required)
dcim_create_site	Create site	name, slug (required), status
dcim_update_site	Update site	id (required), fields to update

Devices (4):

Tool	Description	Parameters
dcim_list_devices	List devices (servers/VPS)	name, site_id, status, role_id
dcim_get_device	Get device by ID	id (required)
dcim_create_device	Create device	name, device_type, role, site (required)
dcim_update_device	Update device	id (required), fields to update

Interfaces (3):

Tool	Description	Parameters
dcim_list_interfaces	List device interfaces	device_id, name, type
dcim_get_interface	Get interface by ID	id (required)
dcim_create_interface	Create interface	device, name, type (required)

IPAM: IPs, Prefixes, Services (10 tools)

IP Addresses (4):

Tool	Description	Parameters
ipam_list_ip_addresses	List IP addresses	address, device_id, status
ipam_get_ip_address	Get IP by ID	id (required)
ipam_create_ip_address	Create IP address	address (required), status, assigned_object_type
ipam_update_ip_address	Update IP address	id (required), fields to update

Prefixes (3):

Tool	Description	Parameters
ipam_list_prefixes	List prefixes	prefix, site_id, status
ipam_get_prefix	Get prefix by ID	id (required)
ipam_create_prefix	Create prefix	prefix (required), status, site

Services (3):

Tool	Description	Parameters
ipam_list_services	List services (apps/databases)	device_id, virtual_machine_id, name
ipam_get_service	Get service by ID	id (required)
ipam_create_service	Create service	name, ports, protocol (required), device, virtual_machine

Virtualization: Clusters, VMs, VM Interfaces (10 tools)

Clusters (3):

Tool	Description	Parameters
virt_list_clusters	List virtualization clusters	name, site_id
virt_get_cluster	Get cluster by ID	id (required)
virt_create_cluster	Create cluster	name, type (required), site

Virtual Machines (4):

Tool	Description	Parameters
virt_list_vms	List VMs	name, cluster_id, site_id, status
virt_get_vm	Get VM by ID	id (required)
virt_create_vm	Create VM	name, cluster (required), vcpus, memory, disk
virt_update_vm	Update VM	id (required), fields to update

VM Interfaces (3):

Tool	Description	Parameters
virt_list_vm_ifaces	List VM interfaces	virtual_machine_id
virt_get_vm_iface	Get VM interface by ID	id (required)
virt_create_vm_iface	Create VM interface	virtual_machine, name (required)

Extras: Tags, Journal Entries (6 tools)

Tags (3):

Tool	Description	Parameters
extras_list_tags	List tags	name
extras_get_tag	Get tag by ID	id (required)
extras_create_tag	Create tag	name, slug (required), color

Journal Entries (3):

Tool	Description	Parameters
extras_list_journal_entries	List journal entries	assigned_object_type, assigned_object_id
extras_get_journal_entry	Get journal entry by ID	id (required)
extras_create_journal_entry	Create journal entry	assigned_object_type, assigned_object_id, comments (required), kind

Configuration

All configuration is done via environment variables in ~/.config/claude/netbox.env:

Variable	Required	Default	Description
NETBOX_API_URL	Yes	—	NetBox API URL (e.g., https://netbox.example.com/api)
NETBOX_API_TOKEN	Yes	—	NetBox API token
NETBOX_VERIFY_SSL	No	true	Verify SSL certificates
NETBOX_TIMEOUT	No	30	Request timeout in seconds

Architecture

Hybrid Configuration

• System-level: ~/.config/claude/netbox.env (credentials)
• Project-level: .env (optional overrides)

Tool Routing

Tool names follow the pattern {module}_{action}_{resource}:

• dcim_list_sites → DCIMTools.list_sites()
• ipam_create_service → IPAMTools.create_service()
• virt_list_vms → VirtualizationTools.list_virtual_machines()

Shortened names (virt_*) are mapped via TOOL_NAME_MAP to meet the 28-character MCP limit.

Error Handling

All tools return JSON responses. Errors are caught and returned as:

{
  "error": "Error message",
  "status_code": 404
}

Development

Testing

# Test import
python -c "from mcp_server.server import NetBoxMCPServer; print('OK')"

# Test tool count
python -c "from mcp_server.server import TOOL_DEFINITIONS; print(f'{len(TOOL_DEFINITIONS)} tools')"

File Structure

netbox/
├── mcp_server/
│   ├── __init__.py
│   ├── server.py          # Main MCP server (37 TOOL_DEFINITIONS)
│   ├── config.py          # Configuration loader
│   ├── netbox_client.py   # HTTP client wrapper
│   └── tools/
│       ├── __init__.py
│       ├── dcim.py        # Sites, Devices, Interfaces
│       ├── ipam.py        # IPs, Prefixes, Services
│       ├── virtualization.py  # Clusters, VMs, VM Interfaces
│       └── extras.py      # Tags, Journal Entries
├── .venv/                 # Python virtual environment
├── requirements.txt
└── README.md

Troubleshooting

MCP Server Won't Start

Check configuration:

cat ~/.config/claude/netbox.env

Test credentials:

curl -H "Authorization: Token YOUR_TOKEN" https://netbox.example.com/api/

Tools Not Appearing in Claude

Verify MCP registration:

cat ~/.claude/mcp.json  # or project-level .mcp.json

Check MCP server logs: Claude Code will show MCP server stderr in the UI.

Connection Errors

• Verify NETBOX_API_URL ends with /api
• Check firewall/network connectivity to NetBox instance
• Ensure API token has required permissions

License

MIT License - See LICENSE file for details.

Contributing

This MCP server is part of the leo-claude-mktplace project. For issues or contributions, refer to the main repository.