NetBox MCP Server 使用说明

项目简介

NetBox MCP Server 是一个基于 Model Context Protocol (MCP) 构建的服务器，专门为 NetBox 平台设计。它充当 LLM (大型语言模型) 客户端和 NetBox 之间的桥梁，使得 LLM 能够安全、便捷地访问和查询 NetBox 中存储的网络基础设施数据。通过预定义的工具，LLM 可以获取设备信息、搜索网络资源，并根据 ID 查询特定对象，从而实现更智能的网络管理和自动化应用。

主要功能点

数据访问工具: 提供 'get_objects', 'search_netbox', 'get_object_by_id' 等工具，允许 LLM 客户端查询 NetBox 中各种网络资源，例如设备、IP 地址、站点等。
基于 NetBox API: 通过 NetBox API 与 NetBox 系统交互，确保数据访问的准确性和实时性。
可扩展的对象类型: 支持 NetBox 核心对象类型，并可通过扩展支持更多对象类型（当前版本已支持丰富的核心对象）。
易于部署和配置: 使用简单的环境变量配置 NetBox 连接信息，快速启动 MCP 服务器。
符合 MCP 标准: 遵循 Model Context Protocol 规范，可以与任何兼容 MCP 协议的 LLM 客户端无缝集成。

安装步骤

准备 NetBox API Token: 在 NetBox 中创建一个只读权限的 API Token，确保该 Token 具有访问您希望通过 MCP 服务器开放的数据的权限。
安装依赖: 在 netbox-mcp-server 仓库目录下，运行以下命令安装项目依赖：
```
uv add -r requirements.txt
```
请确保您已安装 'uv' 包管理器。如果未安装，请先安装 'uv'。
验证服务器运行: 设置 NetBox URL 和 API Token 环境变量，并运行 'server.py' 脚本以验证服务器是否可以正常启动：
```
NETBOX_URL=https://netbox.example.com/ NETBOX_TOKEN=<your-api-token> uv run server.py
```
请将 'https://netbox.example.com/' 替换为您的 NetBox 实例 URL，'<your-api-token>' 替换为您在步骤 1 中创建的 API Token。

服务器配置 (MCP 客户端配置)

为了让 MCP 客户端（例如 Claude Desktop）连接到 netbox-mcp-server，您需要在客户端中添加 MCP 服务器配置。以下是 JSON 格式的配置示例，请根据您的实际情况进行调整：

{
  "mcpServers": {
        "netbox": {
            "command": "uv",
            "args": [
                "--directory",
                "/path/to/netbox-mcp-server",  // 请替换为 netbox-mcp-server 仓库的实际路径
                "run",
                "server.py"
            ],
            "env": {
                "NETBOX_URL": "https://netbox.example.com/", // 请替换为您的 NetBox 实例 URL
                "NETBOX_TOKEN": "<your-api-token>"  // 请替换为您的 NetBox API Token
            }
        }
}

配置参数说明:

'"server name": "netbox"': 为您的 MCP 服务器指定一个名称，例如 "netbox"，您可以自定义。
'"command": "uv"': 指定用于启动服务器的命令，这里使用 'uv' 包管理器来运行 Python 脚本。
'"args": [...]': 启动命令的参数列表：
- '"--directory", "/path/to/netbox-mcp-server"': 指定 netbox-mcp-server 仓库所在的目录路径，请务必替换为实际路径。
- '"run", "server.py"': 指示 'uv' 运行 'server.py' 脚本。
'"env": {...}': 环境变量配置：
- '"NETBOX_URL": "https://netbox.example.com/"': 请替换为您的 NetBox 实例的完整 URL，例如 'https://your-netbox-domain.com/'。
- '"NETBOX_TOKEN": "<your-api-token>"': 请替换为您在 NetBox 中创建的 API Token。

请注意，您需要根据您的操作系统和 'uv' 的安装路径，调整 '"command"' 和 '"args"' 中的路径信息。Windows 系统下，路径可能需要使用反斜杠 '' 并进行转义，例如 'C:\Users\myuser\.local\bin\uv' 和 'C:\Users\myuser\netbox-mcp-server'。

基本使用方法

配置完成后，在您的 LLM 客户端中选择已配置的 "netbox" MCP 服务器。您可以使用自然语言指令，结合提供的工具来查询 NetBox 数据。例如：

> 使用 get_objects 工具，查询 object_type 为 devices，filters 为 {"site": "Equinix DC14"} 的设备列表
> 使用 search_netbox 工具，查询 query 为 "Cisco devices" 的结果
> 使用 get_object_by_id 工具，查询 object_type 为 ip-addresses，object_id 为 123 的 IP 地址详细信息

更自然的提问方式示例：

> 获取 'Equinix DC14' 站点的所有设备
> 告诉我网络中思科设备的型号和数量？
> 123号 IP 地址的详细信息是什么？

LLM 客户端会将这些自然语言指令转换为对 MCP 服务器工具的调用，并将结果返回给您。

netbox mcp server