by netboxlabs
Model Context Protocol (MCP) server for read-only interaction with NetBox data in LLMs
# Add to your Claude Code skills
git clone https://github.com/netboxlabs/netbox-mcp-serverGuides for using mcp servers skills like netbox-mcp-server.
No comments yet. Be the first to share your thoughts!
Top skills in this category by stars
⚠️ Breaking Change in v1.0.0: The project structure has changed. If upgrading from v0.1.0, update your configuration:
- Change
uv run server.pytouv run netbox-mcp-server- Update Claude Desktop/Code configs to use
netbox-mcp-serverinstead ofserver.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.
The server is intentionally simple — easy to get started with, hard to misuse (read-only by default, no plugin surface), and easy to fork and adapt. Forking under Apache 2.0 is a first-class path for users who need capabilities beyond the project's scope.
| 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: Core NetBox object types are always available. Plugin object types can be auto-discovered — see Plugin Object Type Discovery. Advanced features (GraphQL, dynamic model discovery, etc.) are deliberately out of scope — see CONTRIBUTING.md for the full scope statement and rationale.
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.
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:
/path/to/netbox-mcp-server with the absolute path to your local clone-- separator distinguishes Claude Code flags from the server command--scope project to share the configuration via .mcp.json in version control--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.
For HTTP transport, first start the server manually:
# Start the server with HTTP transport (using .env or environment variables)
NETBOX_URL=https://netbox.example.com/ \
NETBOX_TOKEN=<your-api-token> \
TRANSPORT=http \
uv run netbox-mcp-server
Then add the running server to Claude Code:
# Add the HTTP MCP server (note: URL must include http:// or https:// prefix)
claude mcp add --transport http netbox http://127.0.0.1:8000/mcp
Important notes:
http:// or https://)/mcp when using HTTP transportclaude mcp list - you should see a ✓ next to the server nameAdd 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\\uvandC:\\Users\\myuser\\netbox-mcp-server. For detailed troubleshooting, consult the MCP quickstart.
> 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
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:
['id', 'name', 'status', 'device_type', 'site', 'primary_ip4']['id', 'address', 'status', 'dns_name', 'description']['id', 'name', 'type', 'enabled', 'device']['id', 'name', 'status', 'region', 'description']The fields parameter uses NetBox's native field filtering. See the NetBox API documentation for details.
The server supports multiple configuration sources with the following precedence (highest to lowest):
.env file in the project root| 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 | http | stdio | No | MCP transport protocol |
| HOST | String | 127.0.0.1 | If HTTP | Host address for HTTP server |
| PORT | Integer | 8000 | If HTTP | Port for HTTP server |
| VERIFY_SSL | Boolean | true | No | Whether to verify SSL certificates |
| ENABLE_PLUGIN_DISCOVERY | Boolean | false | No | Auto-discover plugin object types at startup |
| LOG_LEVEL | DEBUG | INFO | WARNING | ERROR | CRITICAL | INFO | No | Logging verbosity |
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>"
}
}
}
}
For web-based MCP clients using HTTP/SSE transport:
# Using environment variables
export NETBOX_URL=https://netbox.example.com/
export NETBOX_TOKEN=<your-api-token>
export TRANSPORT=http
export HOST=127.0.0.1
export PORT=8000
uv run netbox-mcp-server
# Or using CLI arguments
uv run netbox-mcp-server \
--netbox-url https://netbox.example.com/ \
--netbox-token <your-api-token> \
--transport http \
--host 127.0.0.1 \
--port 8000
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)
TRANSPORT=stdio
# HTTP Transport Settings (only used if TRANSPORT=http)
# HOST=127.0.0.1
# PORT=8000
# Security (optional, defaults to true)
VERIFY_SSL=true
# Plugin Discovery (optional, defaults to false)
# ENABLE_PLUGIN_DISCOVERY=true
# Logging (optional, defaults to INFO)
LOG_LEVEL=INFO
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 http --port 9000 # Custom HTTP port
Pre-built multi-arch images (linux/amd64, linux/arm64) are published to Docker Hub on every tagged release:
docker pull netboxlabs/netbox-mcp-server:latest
Pin to a specific version in production. The latest tag tracks the most recent release and can change without notice. See the releases page for available versions:
docker pull netboxlabs/netbox-mcp-server:<X.Y.Z> # exact version
docker pull netboxlabs/netbox-mcp-server:<X.Y> # latest within a minor
docker pull netboxlabs/netbox-mcp-server:<X> # latest within a major
Verify image provenance (optional but recommended). Images are signed with cosign (keyless, via GitHub OIDC) and ship with SLSA build provenance:
cosign verify \
--certificate-identity-regexp '^https://github.com/netboxlabs/netbox-mcp-server/' \
--certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \
netboxlabs/netbox-mcp-server:<tag>
Build and run the NetBox MCP server in a container:
# Build the image
docker build -t netbox-mcp-server:latest .
# Run with HTTP transport (required for Docker containers)
docker run --rm \
-e NETBOX_URL=https://netbox.example.com/ \
-e NETBOX_TOKEN=<your-api-token> \
-e TRANSPORT=http \
-e HOST=0.0.0.0 \