NetBox MCP Server

1# NetBox MCP Server
2 
3A small Model Context Protocol (MCP) server built with FastMCP that provides an interface to a NetBox instance.
4 
5This 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.
6 
7## Architecture (FastMCP + streaming HTTP)
8 
9- FastMCP: The MCP tool registry and runtime. Tools are defined in `app.py` and decorated with `@mcp.tool`.
10- NetBoxClient: a tiny async helper in `app.py` that wraps `httpx.AsyncClient` to call the NetBox API.
11- 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.
12 
13Conceptually the flow is:
14 
151. Client connects to the FastMCP streaming HTTP endpoint.
162. Client requests a tool (for example, `search_sites` or `get_site_group_details`).
173. FastMCP calls the associated Python function in `app.py`, which may in turn call NetBox via `NetBoxClient`.
184. The result is streamed back over the HTTP transport as it becomes available.
19 
20> 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.
21 
22## Environment variables
23 
24Set these before running the server:
25 
26- `NETBOX_URL` - Base URL to your NetBox instance (default: `https://netbox.example.com`).
27- `NETBOX_TOKEN` - NetBox API token with read permissions.
28- `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.
29 
30Example (macOS / zsh):
31 
32```bash
33export NETBOX_URL="https://netbox.example.com"
34export NETBOX_TOKEN="0123456789abcdef0123456789abcdef01234567"
35export MCP_PORT=8000
36```
37 
38## Run the server
39 
40Start the MCP server with Python:
41 
42```bash
43python3 app.py
44```
45 
46The server will bind to 0.0.0.0 on the configured port and serve the FastMCP HTTP transport.
47 
48## Tools included
49 
50`app.py` registers MCP tools for NetBox resources. Examples included in this repository:
51 
52- `search_sites` — search of `dcim/sites/` (supports partial/case-insensitive name queries)
53- `get_site_details` — site lookup
54- `search_site_groups` — search of `dcim/site-groups/` (supports `name__ic`)
55- `get_site_group_details` — single site-group lookup by `id`
56 
57You can add more tools following the repository conventions: each NetBox resource has a `search_<resource>` and `get_<resource>_details` tool.
58 
59## Verifying / testing
60 
61- Quick syntax check:
62 
63```bash
64python3 -m py_compile app.py
65```
66 
67- Start the server and use an HTTP client that supports streaming (for example, `curl --no-buffer` or a custom MCP client) to connect to the FastMCP HTTP transport and invoke tools.
68 
69Because the exact HTTP request shape (paths, headers and payload) is defined by the FastMCP runtime and clients, prefer using an existing MCP client library where available. If you're building a custom client, make sure it supports reading chunked responses so streamed results can be consumed incrementally.
70 
71## Contributing
72 
73If you add tools, follow the repo conventions documented in `.github/copilot-instructions.md`: each resource should have a `search_` and a `get_` tool with descriptive docstrings and consistent parameter mapping.
74 
75## License
76 
77This project is provided as-is.
78