NetBox MCP Server

# NetBox MCP Server with mcpo Integration This guide shows how to expose your NetBox MCP server via [mcpo](https://github.com/open-webui/mcpo) to make it accessible through standard OpenAPI endpoints for use with OpenAI-compatible LLMs. ## 🚀 Quick Start ### 1. Prerequisites - NetBox instance running (local or remote) - Read-only API token from NetBox - Python 3.13+ with uv ### 2. Setup 1. **Install dependencies:** ```bash uv sync ``` 2. **Configure NetBox connection:** Update `mcpo-config.json` with your NetBox details: ```json { "mcpServers": { "netbox": { "command": "uv", "args": [ "--directory", "/path/to/netbox-mcp-server", "run", "server.py" ], "env": { "NETBOX_URL": "http://your-netbox-instance.com/", "NETBOX_TOKEN": "your-read-only-api-token" } } } } ``` 3. **Start mcpo server:** ```bash uv run mcpo --config mcpo-config.json --port 8000 --api-key "netbox-secret-key" ``` ### 3. Test the Integration Run the test script to verify everything works: ```bash ./test_netbox_mcp.py ``` ## 🔧 Available Endpoints Your NetBox MCP server is now exposed via OpenAPI at: - **Base URL:** `http://localhost:8000/netbox/` - **API Documentation:** `http://localhost:8000/docs` - **OpenAPI Schema:** `http://localhost:8000/openapi.json` ### Available Tools | Tool | Endpoint | Description | |------|----------|-------------| | `netbox_get_objects` | `POST /netbox/netbox_get_objects` | Get objects by type with filters | | `netbox_get_object_by_id` | `POST /netbox/netbox_get_object_by_id` | Get specific object by ID | | `netbox_get_changelogs` | `POST /netbox/netbox_get_changelogs` | Get change history records | ## 🤖 OpenAI Integration ### Function Schemas for OpenAI Here are the function definitions you can use with OpenAI-compatible LLMs: ```json [ { "name": "netbox_get_objects", "description": "Get objects from NetBox based on their type and filters", "parameters": { "type": "object", "properties": { "object_type": { "type": "string", "description": "Type of NetBox object (e.g., 'devices', 'ip-addresses', 'sites')" }, "filters": { "type": "object", "description": "Filters to apply to the API call" } }, "required": ["object_type"] } }, { "name": "netbox_get_object_by_id", "description": "Get detailed information about a specific NetBox object by its ID", "parameters": { "type": "object", "properties": { "object_type": { "type": "string", "description": "Type of NetBox object" }, "object_id": { "type": "integer", "description": "The numeric ID of the object" } }, "required": ["object_type", "object_id"] } }, { "name": "netbox_get_changelogs", "description": "Get object change records (changelogs) from NetBox based on filters", "parameters": { "type": "object", "properties": { "filters": { "type": "object", "description": "Filters to apply to the API call" } }, "required": [] } } ] ``` ### Example Usage ```python import requests # Call NetBox tool via OpenAPI def call_netbox_tool(tool_name, arguments): response = requests.post( f"http://localhost:8000/netbox/{tool_name}", headers={ "Authorization": "Bearer netbox-secret-key", "Content-Type": "application/json" }, json=arguments ) return response.json() # Get all devices devices = call_netbox_tool("netbox_get_objects", { "object_type": "devices", "filters": {"limit": 10} }) # Get specific device device = call_netbox_tool("netbox_get_object_by_id", { "object_type": "devices", "object_id": 1 }) ``` ## 📋 Supported NetBox Object Types Your MCP server supports all core NetBox object types: ### DCIM (Device and Infrastructure) - `devices`, `device-types`, `device-roles`, `manufacturers` - `sites`, `regions`, `locations`, `site-groups` - `racks`, `rack-reservations`, `rack-roles` - `interfaces`, `front-ports`, `rear-ports`, `console-ports` - `power-ports`, `power-outlets`, `power-panels`, `power-feeds` - `cables`, `virtual-chassis` ### IPAM (IP Address Management) - `ip-addresses`, `prefixes`, `aggregates`, `ip-ranges` - `vlans`, `vlan-groups`, `vrfs` - `services`, `fhrp-groups`, `route-targets` - `asns`, `asn-ranges`, `rirs`, `roles` ### Circuits - `circuits`, `circuit-types`, `circuit-terminations` - `providers`, `provider-networks` ### Virtualization - `virtual-machines`, `vm-interfaces` - `clusters`, `cluster-groups`, `cluster-types` ### Tenancy - `tenants`, `tenant-groups` - `contacts`, `contact-groups`, `contact-roles` ### VPN - `tunnels`, `tunnel-groups` - `ike-policies`, `ike-proposals` - `ipsec-policies`, `ipsec-profiles`, `ipsec-proposals` - `l2vpns` ### Wireless - `wireless-lans`, `wireless-lan-groups`, `wireless-links` ### Extras - `tags`, `custom-fields`, `config-contexts` - `export-templates`, `image-attachments` - `jobs`, `saved-filters`, `scripts`, `webhooks` ## 🔒 Security - The mcpo server uses API key authentication - Your NetBox token should be read-only - Consider using environment variables for sensitive data - Run mcpo behind a reverse proxy for production use ## 🐳 Docker Support You can also run this in Docker: ```bash # Build the image docker build -t netbox-mcp-server . # Run with mcpo docker run -p 8000:8000 \ -e NETBOX_URL=http://your-netbox-instance.com/ \ -e NETBOX_TOKEN=your-token \ netbox-mcp-server ``` ## 🛠️ Troubleshooting ### Common Issues 1. **Connection refused:** Make sure mcpo server is running on port 8000 2. **Authentication failed:** Check your API key and NetBox token 3. **404 errors:** Verify the endpoint URLs are correct (`/netbox/` prefix) 4. **Empty results:** Check your NetBox permissions and filters ### Debug Mode Enable debug logging in your MCP server: ```python mcp = FastMCP("NetBox", log_level="DEBUG") ``` ### Test Individual Endpoints ```bash # Test OpenAPI schema curl -H "Authorization: Bearer netbox-secret-key" \ http://localhost:8000/openapi.json # Test a tool call curl -X POST \ -H "Authorization: Bearer netbox-secret-key" \ -H "Content-Type: application/json" \ -d '{"object_type": "devices", "filters": {"limit": 1}}' \ http://localhost:8000/netbox/netbox_get_objects ``` ## 📚 Additional Resources - [mcpo Documentation](https://github.com/open-webui/mcpo) - [NetBox API Documentation](https://netbox.readthedocs.io/en/stable/api/overview/) - [OpenAI Function Calling Guide](https://platform.openai.com/docs/guides/function-calling) - [MCP Protocol Specification](https://modelcontextprotocol.io/) ## 🤝 Contributing Contributions are welcome! Please open an issue or submit a PR. ## 📄 License This project is licensed under the Apache 2.0 license.