Content
# NetBox MCP Server
A Model Context Protocol (MCP) server that connects to NetBox and exposes network infrastructure data for use with Claude and other MCP-compatible LLMs.
## Overview
This server provides a bridge between NetBox and MCP-compatible LLMs like Claude, allowing you to:
- Query and analyze your network infrastructure data
- Check device configurations and connections
- Examine virtualization clusters and virtual machines
- Analyze VLANs, IP address allocations, and more
- Generate network topology information
- Detect NVMe storage in clusters
The server exposes:
- **Tools**: Functions that perform operations
## Requirements
- Python 3.10 or higher
- NetBox instance with API access
- NetBox API token with read permissions
- `httpx` library for HTTP requests
- `mcp` Python SDK for Model Context Protocol
## Installation
### Using uv (recommended)
```bash
# Create a virtual environment
uv venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
# Install required packages
uv add mcp httpx
```
### Using pip
```bash
# Create a virtual environment
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# Install required packages
pip install mcp httpx
```
## Usage
### Running the Server Directly
```bash
python netbox_server.py --url https://your-netbox-instance.example.com --token your-api-token
```
You can also set environment variables instead of using command-line arguments:
```bash
export NETBOX_URL="https://your-netbox-instance.example.com"
export NETBOX_TOKEN="your-api-token"
python netbox_server.py
```
### Integration with Claude Desktop
To integrate with Claude Desktop:
1. Install Claude Desktop from [https://claude.ai/download](https://claude.ai/download)
2. Open the Claude menu and select "Settings..."
3. Click on "Developer" in the left sidebar
4. Click on "Edit Config"
5. Add the NetBox server configuration to `claude_desktop_config.json`:
```json
{
"mcpServers": {
"netbox": {
"command": "python",
"args": [
"/path/to/netbox_server.py",
"--url",
"https://your-netbox-instance.example.com",
"--token",
"your-api-token"
]
}
}
}
```
6. Save the file and restart Claude Desktop
## Available Features
### Tools
The server provides these tools:
- `get_all_clusters` - Get list of all clusters with key information
- `get_cluster_virtual_machines` - Get all VMs in a specific cluster
- `get_cluster_interfaces` - Get all interfaces from all VMs in a cluster
## Example Queries for Claude
Once the server is connected to Claude Desktop, you can ask questions like:
- "Show me a list of all clusters in our NetBox instance"
- "Show me all the virtual machines in our primary cluster"
## License
This project is licensed under the MIT License - see the LICENSE file for details.
## Acknowledgments
- [NetBox](https://github.com/netbox-community/netbox) - Network infrastructure modeling
- [Model Context Protocol](https://modelcontextprotocol.io) - Protocol for providing context to LLMs
- [Claude](https://claude.ai) - Anthropic's AI assistant
