personal-projects/leo-claude-mktplace
Template
0
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
d84425cbb0679a31252c58d156f1a498eac19f64
leo-claude-mktplace/plugins/cmdb-assistant/mcp-servers/netbox/README.md
lmiranda d84425cbb0 refactor: bundle MCP servers inside plugins for cache compatibility 
Claude Code only caches the plugin directory when installed from a
marketplace, not parent directories. This broke the shared mcp-servers/
architecture because relative paths like ../../mcp-servers/ resolved
to non-existent locations in the cache.

Changes:
- Move gitea and wikijs MCP servers into plugins/projman/mcp-servers/
- Move netbox MCP server into plugins/cmdb-assistant/mcp-servers/
- Update .mcp.json files to use ${CLAUDE_PLUGIN_ROOT}/mcp-servers/
- Update setup.sh to handle new bundled structure
- Add netbox.env config template to setup.sh
- Update CLAUDE.md and CANONICAL-PATHS.md documentation

This ensures plugins work correctly when installed and cached.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2025-12-15 17:23:02 -05:00

298 lines
8.6 KiB
Markdown
Raw Blame History

# NetBox MCP Server
MCP (Model Context Protocol) server for comprehensive NetBox API integration with Claude Code.
## Overview
This MCP server provides Claude Code with full access to the NetBox REST API, enabling infrastructure management, documentation, and automation workflows. It covers all major NetBox application areas:
- **DCIM** - Sites, Locations, Racks, Devices, Interfaces, Cables, Power
- **IPAM** - IP Addresses, Prefixes, VLANs, VRFs, ASNs, Services
- **Circuits** - Providers, Circuits, Terminations
- **Virtualization** - Clusters, Virtual Machines, VM Interfaces
- **Tenancy** - Tenants, Contacts, Contact Assignments
- **VPN** - Tunnels, IKE/IPSec Policies, L2VPN
- **Wireless** - Wireless LANs, Links, Groups
- **Extras** - Tags, Custom Fields, Webhooks, Config Contexts, Audit Log
## Installation
### 1. Clone and Setup
```bash
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:
```bash
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 (`~/.config/claude/mcp.json` or project `.mcp.json`):
```json
{
"mcpServers": {
"netbox": {
"command": "/path/to/mcp-servers/netbox/.venv/bin/python",
"args": ["-m", "mcp_server.server"],
"cwd": "/path/to/mcp-servers/netbox"
}
}
}
```
## Configuration
### Environment Variables
| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `NETBOX_API_URL` | Yes | - | Full URL to NetBox API (e.g., `https://netbox.example.com/api`) |
| `NETBOX_API_TOKEN` | Yes | - | API authentication token |
| `NETBOX_VERIFY_SSL` | No | `true` | Verify SSL certificates |
| `NETBOX_TIMEOUT` | No | `30` | Request timeout in seconds |
### Configuration Hierarchy
1. **System-level** (`~/.config/claude/netbox.env`): Credentials and defaults
2. **Project-level** (`.env` in current directory): Optional overrides
## Available Tools
### DCIM (Data Center Infrastructure Management)
| Tool | Description |
|------|-------------|
| `dcim_list_sites` | List all sites |
| `dcim_get_site` | Get site details |
| `dcim_create_site` | Create a new site |
| `dcim_update_site` | Update a site |
| `dcim_delete_site` | Delete a site |
| `dcim_list_devices` | List all devices |
| `dcim_get_device` | Get device details |
| `dcim_create_device` | Create a new device |
| `dcim_update_device` | Update a device |
| `dcim_delete_device` | Delete a device |
| `dcim_list_interfaces` | List device interfaces |
| `dcim_create_interface` | Create an interface |
| `dcim_list_racks` | List all racks |
| `dcim_create_rack` | Create a new rack |
| `dcim_list_cables` | List all cables |
| `dcim_create_cable` | Create a cable connection |
| ... and many more |
### IPAM (IP Address Management)
| Tool | Description |
|------|-------------|
| `ipam_list_prefixes` | List IP prefixes |
| `ipam_create_prefix` | Create a prefix |
| `ipam_list_available_prefixes` | List available child prefixes |
| `ipam_create_available_prefix` | Auto-allocate a prefix |
| `ipam_list_ip_addresses` | List IP addresses |
| `ipam_create_ip_address` | Create an IP address |
| `ipam_list_available_ips` | List available IPs in prefix |
| `ipam_create_available_ip` | Auto-allocate an IP |
| `ipam_list_vlans` | List VLANs |
| `ipam_create_vlan` | Create a VLAN |
| `ipam_list_vrfs` | List VRFs |
| ... and many more |
### Circuits
| Tool | Description |
|------|-------------|
| `circuits_list_providers` | List circuit providers |
| `circuits_create_provider` | Create a provider |
| `circuits_list_circuits` | List circuits |
| `circuits_create_circuit` | Create a circuit |
| `circuits_list_circuit_terminations` | List terminations |
| ... and more |
### Virtualization
| Tool | Description |
|------|-------------|
| `virtualization_list_clusters` | List clusters |
| `virtualization_create_cluster` | Create a cluster |
| `virtualization_list_virtual_machines` | List VMs |
| `virtualization_create_virtual_machine` | Create a VM |
| `virtualization_list_vm_interfaces` | List VM interfaces |
| ... and more |
### Tenancy
| Tool | Description |
|------|-------------|
| `tenancy_list_tenants` | List tenants |
| `tenancy_create_tenant` | Create a tenant |
| `tenancy_list_contacts` | List contacts |
| `tenancy_create_contact` | Create a contact |
| ... and more |
### VPN
| Tool | Description |
|------|-------------|
| `vpn_list_tunnels` | List VPN tunnels |
| `vpn_create_tunnel` | Create a tunnel |
| `vpn_list_l2vpns` | List L2VPNs |
| `vpn_list_ike_policies` | List IKE policies |
| `vpn_list_ipsec_policies` | List IPSec policies |
| ... and more |
### Wireless
| Tool | Description |
|------|-------------|
| `wireless_list_wireless_lans` | List wireless LANs |
| `wireless_create_wireless_lan` | Create a WLAN |
| `wireless_list_wireless_links` | List wireless links |
| ... and more |
### Extras
| Tool | Description |
|------|-------------|
| `extras_list_tags` | List all tags |
| `extras_create_tag` | Create a tag |
| `extras_list_custom_fields` | List custom fields |
| `extras_list_webhooks` | List webhooks |
| `extras_list_journal_entries` | List journal entries |
| `extras_create_journal_entry` | Create journal entry |
| `extras_list_object_changes` | View audit log |
| `extras_list_config_contexts` | List config contexts |
| ... and more |
## Usage Examples
### List all devices at a site
```
Use the dcim_list_devices tool with site_id filter to see all devices at site 5
```
### Create a new prefix and allocate IPs
```
1. Use ipam_create_prefix to create 10.0.1.0/24
2. Use ipam_list_available_ips with the prefix ID to see available addresses
3. Use ipam_create_available_ip to auto-allocate the next IP
```
### Document a new server
```
1. Use dcim_create_device to create the device
2. Use dcim_create_interface to add network interfaces
3. Use ipam_create_ip_address to assign IPs to interfaces
4. Use extras_create_journal_entry to add notes
```
### Audit recent changes
```
Use extras_list_object_changes to see recent modifications in NetBox
```
## Architecture
```
mcp-servers/netbox/
├── mcp_server/
│ ├── __init__.py
│ ├── config.py # Configuration loader
│ ├── netbox_client.py # Generic HTTP client
│ ├── server.py # MCP server entry point
│ └── tools/
│ ├── __init__.py
│ ├── dcim.py # DCIM operations
│ ├── ipam.py # IPAM operations
│ ├── circuits.py # Circuits operations
│ ├── virtualization.py
│ ├── tenancy.py
│ ├── vpn.py
│ ├── wireless.py
│ └── extras.py
├── tests/
│ └── __init__.py
├── requirements.txt
└── README.md
```
## API Coverage
This MCP server provides comprehensive coverage of the NetBox REST API v4.x:
- Full CRUD operations for all major models
- Filtering and search capabilities
- Special endpoints (available prefixes, available IPs)
- Pagination handling (automatic)
- Error handling with detailed messages
## Error Handling
The server returns detailed error messages from the NetBox API, including:
- Validation errors
- Authentication failures
- Not found errors
- Permission errors
## Security Notes
- API tokens should be kept secure and not committed to version control
- Use environment variables or the system config file for credentials
- SSL verification is enabled by default
- Consider using read-only tokens for query-only workflows
## Troubleshooting
### Common Issues
1. **Connection refused**: Check `NETBOX_API_URL` is correct and accessible
2. **401 Unauthorized**: Verify your API token is valid
3. **SSL errors**: Set `NETBOX_VERIFY_SSL=false` for self-signed certs (not recommended for production)
4. **Timeout errors**: Increase `NETBOX_TIMEOUT` for slow connections
### Debug Mode
Enable debug logging:
```python
import logging
logging.basicConfig(level=logging.DEBUG)
```
## Contributing
1. Follow the existing code patterns
2. Add tests for new functionality
3. Update documentation for new tools
4. Ensure compatibility with NetBox 4.x API
## License
Part of the Bandit Labs Claude Code Plugins project (`support-claude-mktplace`).
Reference in New Issue View Git Blame Copy Permalink