Cursor AI Integration - randygagnon/netbox-mcp-server GitHub Wiki

Cursor AI Integration

This guide explains how to use the NetBox MCP Server with Cursor AI's Composer feature.

Setup in Cursor

Add NetBox MCP Server

Open Cursor Settings > Features > MCP
Click "+ Add New MCP Server"

Configure the server:

{
  "Name": "netbox",
  "Type": "stdio",
  "Command": "uv run server.py",
  "Working Directory": "/path/to/netbox-mcp-server"
}

Project-Specific Configuration Create .cursor/mcp.json in your project:

{
  "mcpServers": {
    "netbox": {
      "command": "uv",
      "args": [
        "run",
        "server.py"
      ],
      "env": {
        "NETBOX_URL": "https://netbox.example.com/",
        "NETBOX_TOKEN": "your-api-token"
      }
    }
  }
}

Using with Cursor's Agent

The Agent will automatically use NetBox MCP tools when relevant. Here are some effective ways to interact:

Infrastructure Discovery

Agent: Show me all devices in our London datacenter.
Tool: get_objects
Parameters: {
  "object_type": "devices",
  "filters": {
    "site": "london"
  }
}

IP Management

Agent: List all IP addresses in the 10.0.0.0/8 network.
Tool: get_objects
Parameters: {
  "object_type": "ip-addresses",
  "filters": {
    "prefix": "10.0.0.0/8"
  }
}

Global Search

Agent: Find all Cisco switches.
Tool: search_netbox
Parameters: {
  "query": "manufacturer:cisco role:switch",
  "limit": 20
}

Best Practices

Tool Approval
- By default, Cursor will ask for approval before running tools
- Review tool parameters before approving
- Enable "Yolo mode" for trusted environments to run without approval
Query Structure
- Be specific in your requests
- Include relevant filters
- Use natural language
- Reference specific object types when known
Error Handling
- The Agent will show tool errors in the chat
- Review error messages for:
  - Authentication issues
  - Invalid parameters
  - Network connectivity problems
  - Rate limiting
Security Considerations
- Use read-only API tokens
- Don't share .cursor/mcp.json with sensitive data
- Review tool calls before approval
- Monitor tool usage

Example Workflows

Network Inventory

Agent: I need to audit our network equipment.
Steps:
1. List all network devices
2. Get their interfaces
3. Show IP assignments
4. Check connection status

Capacity Planning

Agent: Help me plan datacenter capacity.
Steps:
1. Show rack space utilization
2. List power consumption
3. Check network port availability
4. Review IP address allocation

Troubleshooting

Agent: Debug connectivity for web-server-01.
Steps:
1. Get device details
2. Show interface status
3. List connected devices
4. Check IP configurations

Common Issues

Authentication Errors

Error: Invalid token or insufficient permissions
Solution: Verify NETBOX_TOKEN and permissions

Connection Issues

Error: Cannot connect to NetBox instance
Solution: Check NETBOX_URL and network connectivity

Invalid Parameters

Error: Invalid object_type specified
Solution: Use correct object type from API reference

Tips for Effective Use

Start Broad, Then Refine

Initial: "Show all devices"
Refine: "Show active Cisco devices in London datacenter"

Use Natural Language

Good: "Find all switches with 10G interfaces"
Also Good: "What switches have 10G capability?"

Combine Multiple Tools

"Show me all devices in the London datacenter and their IP addresses"
(Agent will use both get_objects and search_netbox appropriately)

Advanced Usage

Custom Queries

Agent: Find devices that match these criteria:
- Manufacturer: Cisco
- Role: Core Switch
- Status: Active
- Has: 10G interfaces
- Location: Any primary datacenter

Reporting

Agent: Generate a network health report showing:
- Device status summary
- Interface utilization
- IP space usage
- Recent changes

Audit Trails

Agent: Show me all changes in the past week:
- New devices
- IP assignments
- Configuration updates
- Status changes

For more detailed information about available tools and their parameters, see the API Reference page.