NetBox MCP Server

⚠️ Breaking Change in v1.0.0: The project structure has changed. If upgrading from v0.1.0, update your configuration:

Change uv run server.py to uv run netbox-mcp-server

Update Claude Desktop/Code configs to use netbox-mcp-server instead of server.py

Docker users: rebuild images with updated CMD

See CHANGELOG.md for full details

This is a simple read-only Model Context Protocol server for NetBox. It enables you to interact with your data in NetBox directly via LLMs that support MCP.

Tools

Tool	Description
get_objects	Retrieves NetBox core objects based on their type and filters
get_object_by_id	Gets detailed information about a specific NetBox object by its ID
get_changelogs	Retrieves change history records (audit trail) based on filters

Note: the set of supported object types is explicitly defined and limited to the core NetBox objects for now, and won't work with object types from plugins.

Usage

Create a read-only API token in NetBox with sufficient permissions for the tool to access the data you want to make available via MCP.

Install dependencies:

# Using UV (recommended)
uv sync

# Or using pip
pip install -e .

Verify the server can run: NETBOX_URL=https://netbox.example.com/ NETBOX_TOKEN=<your-api-token> uv run netbox-mcp-server
Add the MCP server to your LLM client. See below for some examples with Claude.

Claude Code

Stdio Transport (Default)

Add the server using the claude mcp add command:

claude mcp add --transport stdio netbox \
  --env NETBOX_URL=https://netbox.example.com/ \
  --env NETBOX_TOKEN=<your-api-token> \
  -- uv --directory /path/to/netbox-mcp-server run netbox-mcp-server

Important notes:

Replace /path/to/netbox-mcp-server with the absolute path to your local clone
The -- separator distinguishes Claude Code flags from the server command
Use --scope project to share the configuration via .mcp.json in version control
Use --scope user to make it available across all your projects (default is local)

After adding, verify with /mcp in Claude Code or claude mcp list in your terminal.

SSE Transport

For SSE transport, first start the server manually:

# Start the server with SSE transport (using .env or environment variables)
NETBOX_URL=https://netbox.example.com/ \
NETBOX_TOKEN=<your-api-token> \
TRANSPORT=sse \
uv run netbox-mcp-server

Then add the running server to Claude Code:

# Add the SSE MCP server (note: URL must include http:// or https:// prefix)
claude mcp add --transport sse netbox http://127.0.0.1:8000/sse

Important notes:

The URL must include the protocol prefix (http:// or https://)
The default endpoint is /sse when using SSE transport
Use /mcp endpoint for streamable-http transport
The server must be running before Claude Code can connect
Verify the connection with claude mcp list - you should see a ✓ next to the server name

Claude Desktop

Add the server configuration to your Claude Desktop config file. On Mac, edit ~/Library/Application Support/Claude/claude_desktop_config.json:

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

On Windows, use full, escaped path to your instance, such as C:\\Users\\myuser\\.local\\bin\\uv and C:\\Users\\myuser\\netbox-mcp-server. For detailed troubleshooting, consult the MCP quickstart.

Use the tools in your LLM client. For example:

> Get all devices in the 'Equinix DC14' site
...
> Tell me about my IPAM utilization
...
> What Cisco devices are in my network?
...
> Who made changes to the NYC site in the last week?
...
> Show me all configuration changes to the core router in the last month

Field Filtering (Token Optimization)

Both netbox_get_objects() and netbox_get_object_by_id() support an optional fields parameter to reduce token usage:

# Without fields: ~5000 tokens for 50 devices
devices = netbox_get_objects('devices', {'site': 'datacenter-1'})

# With fields: ~500 tokens (90% reduction)
devices = netbox_get_objects(
    'devices',
    {'site': 'datacenter-1'},
    fields=['id', 'name', 'status', 'site']
)

Common field patterns:

Devices: ['id', 'name', 'status', 'device_type', 'site', 'primary_ip4']
IP Addresses: ['id', 'address', 'status', 'dns_name', 'description']
Interfaces: ['id', 'name', 'type', 'enabled', 'device']
Sites: ['id', 'name', 'status', 'region', 'description']

The fields parameter uses NetBox's native field filtering. See the NetBox API documentation for details.

Configuration

The server supports multiple configuration sources with the following precedence (highest to lowest):

Command-line arguments (highest priority)
Environment variables
.env file in the project root
Default values (lowest priority)

Configuration Reference

Setting	Type	Default	Required	Description
`NETBOX_URL`	URL	-	Yes	Base URL of your NetBox instance (e.g., https://netbox.example.com/)
`NETBOX_TOKEN`	String	-	Yes	API token for authentication
`TRANSPORT`	`stdio` \| `sse` \| `streamable-http`	`stdio`	No	MCP transport protocol
`HOST`	String	`127.0.0.1`	If SSE/HTTP	Host address for network server
`PORT`	Integer	`8000`	If SSE/HTTP	Port for network server
`VERIFY_SSL`	Boolean	`true`	No	Whether to verify SSL certificates
`LOG_LEVEL`	`DEBUG` \| `INFO` \| `WARNING` \| `ERROR` \| `CRITICAL`	`INFO`	No	Logging verbosity

Transport Examples

Stdio Transport (Claude Desktop/Code)

For local Claude Desktop or Claude Code usage with stdio transport:

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

SSE / Streamable HTTP Transport (Web Clients, LibreChat)

For web-based MCP clients (including LibreChat) using SSE or Streamable HTTP transport:

# Using environment variables (SSE - recommended for LibreChat)
export NETBOX_URL=https://netbox.example.com/
export NETBOX_TOKEN=<your-api-token>
export TRANSPORT=sse
export HOST=127.0.0.1
export PORT=8000

uv run netbox-mcp-server

# Or using Streamable HTTP transport
uv run netbox-mcp-server \
  --netbox-url https://netbox.example.com/ \
  --netbox-token <your-api-token> \
  --transport streamable-http \
  --host 127.0.0.1 \
  --port 8000

LibreChat Integration

To use this MCP server with LibreChat, add the following to your librechat.yaml configuration file:

Option 1: SSE Transport (Recommended)

First, start the server:

NETBOX_URL=https://netbox.example.com/ \
NETBOX_TOKEN=<your-api-token> \
TRANSPORT=sse \
HOST=0.0.0.0 \
PORT=8000 \
uv run netbox-mcp-server

Then configure LibreChat:

mcpServers:
  netbox:
    type: sse
    url: http://localhost:8000/sse
    timeout: 30000
    initTimeout: 10000
    serverInstructions: true

Option 2: Streamable HTTP Transport

mcpServers:
  netbox:
    type: streamable-http
    url: http://localhost:8000/mcp
    timeout: 30000
    initTimeout: 10000
    serverInstructions: true

Option 3: Stdio Transport (Direct Process)

mcpServers:
  netbox:
    type: stdio
    command: uv
    args:
      - "--directory"
      - "/path/to/netbox-mcp-server"
      - "run"
      - "netbox-mcp-server"
    env:
      NETBOX_URL: "https://netbox.example.com/"
      NETBOX_TOKEN: "${NETBOX_TOKEN}"  # Reference environment variable
    timeout: 30000
    initTimeout: 10000
    serverInstructions: true

Docker with LibreChat

If running both LibreChat and NetBox MCP Server in Docker, you can use Docker networking:

# docker-compose.yml addition
services:
  netbox-mcp:
    build: ./netbox-mcp-server
    environment:
      - NETBOX_URL=https://netbox.example.com/
      - NETBOX_TOKEN=${NETBOX_TOKEN}
      - TRANSPORT=sse
      - HOST=0.0.0.0
      - PORT=8000
    ports:
      - "8000:8000"

Then in librechat.yaml:

mcpServers:
  netbox:
    type: sse
    url: http://netbox-mcp:8000/sse  # Use Docker service name
    timeout: 30000

mcpSettings:
  allowedDomains:
    - "netbox-mcp"  # Allow internal Docker network hostname

Example .env File

Create a .env file in the project root:

# Core NetBox Configuration
NETBOX_URL=https://netbox.example.com/
NETBOX_TOKEN=your_api_token_here

# Transport Configuration (optional, defaults to stdio)
# Options: stdio, sse, streamable-http
TRANSPORT=stdio

# Network Transport Settings (only used if TRANSPORT=sse or streamable-http)
# HOST=127.0.0.1
# PORT=8000

# Security (optional, defaults to true)
VERIFY_SSL=true

# Logging (optional, defaults to INFO)
LOG_LEVEL=INFO

CLI Arguments

All configuration options can be overridden via CLI arguments:

uv run netbox-mcp-server --help

# Common examples:
uv run netbox-mcp-server --log-level DEBUG --no-verify-ssl  # Development
uv run netbox-mcp-server --transport sse --port 9000        # SSE on custom port
uv run netbox-mcp-server --transport streamable-http        # Streamable HTTP transport

Docker Usage

Standard Docker Image

Build and run the NetBox MCP server in a container:

# Build the image
docker build -t netbox-mcp-server:latest .

# Run with SSE transport (recommended for Docker containers)
docker run --rm \
  -e NETBOX_URL=https://netbox.example.com/ \
  -e NETBOX_TOKEN=<your-api-token> \
  -e TRANSPORT=sse \
  -e HOST=0.0.0.0 \
  -e PORT=8000 \
  -p 8000:8000 \
  netbox-mcp-server:latest

Note: Docker containers require TRANSPORT=sse or TRANSPORT=streamable-http since stdio transport doesn't work in containerized environments.

Connecting to NetBox on your host machine:

If your NetBox instance is running on your host machine (not in a container), you need to use host.docker.internal instead of localhost on macOS and Windows:

# For NetBox running on host (macOS/Windows)
docker run --rm \
  -e NETBOX_URL=http://host.docker.internal:18000/ \
  -e NETBOX_TOKEN=<your-api-token> \
  -e TRANSPORT=sse \
  -e HOST=0.0.0.0 \
  -e PORT=8000 \
  -p 8000:8000 \
  netbox-mcp-server:latest

Note: On Linux, you can use --network host instead, or use the host's IP address directly.

With additional configuration options:

docker run --rm \
  -e NETBOX_URL=https://netbox.example.com/ \
  -e NETBOX_TOKEN=<your-api-token> \
  -e TRANSPORT=sse \
  -e HOST=0.0.0.0 \
  -e LOG_LEVEL=DEBUG \
  -e VERIFY_SSL=false \
  -p 8000:8000 \
  netbox-mcp-server:latest

The server will be accessible at:

SSE transport: http://localhost:8000/sse
Streamable HTTP transport: http://localhost:8000/mcp

Development

Contributions are welcome! Please open an issue or submit a PR.

License

This project is licensed under the Apache 2.0 license. See the LICENSE file for details.

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
.claude/skills/netbox-mcp-testing		.claude/skills/netbox-mcp-testing
.github		.github
src/netbox_mcp_server		src/netbox_mcp_server
tests		tests
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
CHANGELOG.md		CHANGELOG.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README-client.md		README-client.md
README.md		README.md
SECURITY.md		SECURITY.md
claude.md		claude.md
pyproject.toml		pyproject.toml
uv.lock		uv.lock

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

NetBox MCP Server

Tools

Usage

Claude Code

Stdio Transport (Default)

SSE Transport

Claude Desktop

Field Filtering (Token Optimization)

Configuration

Configuration Reference

Transport Examples

Stdio Transport (Claude Desktop/Code)

SSE / Streamable HTTP Transport (Web Clients, LibreChat)

LibreChat Integration

Option 1: SSE Transport (Recommended)

Option 2: Streamable HTTP Transport

Option 3: Stdio Transport (Direct Process)

Docker with LibreChat

Example .env File

CLI Arguments

Docker Usage

Standard Docker Image

Development

License

About

Uh oh!

Releases

Packages

Languages

License

cloudducoeur/netbox-mcp-server

Folders and files

Latest commit

History

Repository files navigation

NetBox MCP Server

Tools

Usage

Claude Code

Stdio Transport (Default)

SSE Transport

Claude Desktop

Field Filtering (Token Optimization)

Configuration

Configuration Reference

Transport Examples

Stdio Transport (Claude Desktop/Code)

SSE / Streamable HTTP Transport (Web Clients, LibreChat)

LibreChat Integration

Option 1: SSE Transport (Recommended)

Option 2: Streamable HTTP Transport

Option 3: Stdio Transport (Direct Process)

Docker with LibreChat

Example .env File

CLI Arguments

Docker Usage

Standard Docker Image

Development

License

About

Resources

License

Security policy

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages