simonpainter/netbox-mcp

A small Model Context Protocol (MCP) server built with FastMCP that provides an interface to a NetBox instance.
This repository exposes NetBox resources (sites, site-groups, devices, etc.) as MCP tools and runs a streaming HTTP transport so clients can connect and receive streamed responses from the MCP server.
Architecture (FastMCP + streaming HTTP)
- FastMCP: The MCP tool registry and runtime. Tools are defined in app.py and decorated with @mcp.tool.
- NetBoxClient: a tiny async helper in app.py that wraps httpx.AsyncClient to call the NetBox API.
- Streaming HTTP transport: the MCP server is started with mcp.run(transport="http", ...) which runs an HTTP server that supports a streaming/chunked response transport. This is useful for clients that want to consume events or long-running responses incrementally rather than waiting for the entire result.
Conceptually the flow is:
1. Client connects to the FastMCP streaming HTTP endpoint.
2. Client requests a tool (for example, search_sites or get_site_group_details).
3. FastMCP calls the associated Python function in app.py, which may in turn call NetBox via NetBoxClient.
4. The result is streamed back over the HTTP transport as it becomes available.
> Note: The low-level HTTP path/shape is provided by the FastMCP runtime. Clients that wish to connect should use a compatible MCP client or an HTTP client that supports reading chunked / streaming responses.
Environment variables
Set these before running the server:
- NETBOX_URL - Base URL to your NetBox instance (default: https://netbox.example.com).
- NETBOX_TOKEN - NetBox API token with read permissions.
- MCP_PORT - Port for the FastMCP HTTP transport. Defaults to 8000 if not set. If the value is not a valid integer, the server will exit with an error.
Example (macOS / zsh):
Run the server
Start the MCP server with Python:
The server will bind to 0.0.0.0 on the configured port and serve the FastMCP HTTP transport.
Tools included
app.py registers MCP tools for NetBox resources. Examples included in this repository:
- search_sites — search of dcim/sites/ (supports partial/case-insensitive name queries)
- get_site_details — site lookup
- search_site_groups — search of dcim/site-groups/ (supports name__ic)
- get_site_group_details — single site-group lookup by id
You can add more tools following the repository conventions: each NetBox resource has a search_ and get_ _details tool.
Verifying / testing
- Quick syntax check: