Installation Guide

This guide will walk you through the process of installing and setting up the NetBox MCP Server.

Prerequisites

• Python 3.13 or higher
• A running NetBox instance
• A NetBox API token with read permissions
• uv package manager (recommended)

Installation Steps

1. Clone the Repository

   git clone https://github.com/randygagnon/netbox-mcp-server.git
   cd netbox-mcp-server
   

2. Install Dependencies

   # Using uv (recommended)
   uv add -r requirements.txt
   
   # Or using pip
   pip install -r requirements.txt
   

3. Create NetBox API Token

   1. Log in to your NetBox instance
   2. Go to your user profile
   3. Navigate to API Tokens
   4. Create a new token with read permissions
   5. Save the token securely

4. Verify Installation

   # Set environment variables
   export NETBOX_URL="https://netbox.example.com/"
   export NETBOX_TOKEN="your-api-token"
   
   # Test the server
   uv run server.py
   

LLM Client Configuration

Claude Desktop (Mac)

Add the following to your Claude Desktop configuration:

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

Windows Configuration

For Windows systems:

• Use full, escaped paths
• Example path format: C:\\Users\\myuser\\.local\\bin\\uv
• Directory path example: C:\\Users\\myuser\\netbox-mcp-server

Verification

To verify your installation:

1. Start your LLM client
2. Try a simple query like: "List all sites in NetBox"
3. You should receive a structured response with your NetBox sites

Troubleshooting

If you encounter issues:

1. Server Won't Start

   • Check Python version (python --version)
   • Verify environment variables are set correctly
   • Ensure all dependencies are installed

2. Authentication Errors

   • Verify your NetBox token is valid
   • Check the token has appropriate permissions
   • Ensure the NetBox URL is correct and accessible

3. Connection Issues

   • Verify your NetBox instance is reachable
   • Check SSL certificate validity
   • Ensure no firewalls are blocking access

For more detailed troubleshooting, see the Troubleshooting guide.