netbox-mcp

Purpose

netbox-mcp is 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 that clients can connect and receive responses streamed from the MCP server.

Key capabilities

• Register MCP tools via FastMCP; tools are defined in app.py using the @mcp.tool decorator.
• Built-in NetBoxClient async helper class that wraps httpx.AsyncClient to call the NetBox API.
• Uses streaming HTTP transport (mcp.run(transport="http", ...)), supporting streaming/chunked responses, suitable for clients that want to consume events incrementally or handle long-running responses.
• Example tools already included in the repository: search_sites (searches dcim/sites/, supports partial/case-insensitive name queries), get_site_details (site lookup), search_site_groups (searches dcim/site-groups/, supports name__ic), get_site_group_details (looks up a single site group by id).
• More tools can be added following the repository conventions: each NetBox resource corresponds to one search_<resource> and one get_<resource>_details tool.

Usage

1. Set environment variables before running the server:
   • NETBOX_URL — the base URL of the NetBox instance (default:https://netbox.example.com）。
   • NETBOX_TOKEN — a NetBox API token with read permissions.
   • MCP_PORT — the port for the FastMCP HTTP transport; defaults to 8000 when unset; if the value is not a valid integer, the server will error out and exit.
2. Example (macOS / zsh): start the MCP server via Python.
3. The server will bind to the configured port on 0.0.0.0 and provide the FastMCP HTTP transport.
4. After a client connects and requests a tool (for example search_sites or get_site_group_details), FastMCP calls the associated Python function in app.py, which may call NetBox via NetBoxClient, and results are streamed back over the HTTP transport as they become available.

Applicable scenarios

Suitable for scenarios that need to interact with NetBox in an MCP manner, especially integrations where the client wants to consume streaming responses incrementally rather than waiting for the complete result.

Limitations

• The project's HTTP paths/format are provided by the FastMCP runtime; clients should use a compatible MCP client or an HTTP client that supports reading chunked/streaming responses.
• Because the exact HTTP request format (paths, headers, and payloads) is defined by the FastMCP runtime and the client, it is recommended to prefer existing MCP client libraries; if building a custom client, ensure it supports reading chunked responses to incrementally consume streaming results.
• If adding tools, follow the repository conventions (documented in .github/copilot-instructions.md): each resource should have search_ and get_ tools, with descriptive docstrings and consistent parameter mapping.
• The project is provided "as is".
• No pricing, cost, or platform information is currently provided.